implementingDITA™ Setting the stage: Creating simple DITA projects that will scale up Anna van Raaphorst Richard H. (Dick) Johnson Authors of the DITA Open Toolkit User Guide VR Communications, Inc. Revised: March 29, 2007

March 2007implementingDITA™: Setting the Stage2 Contents Two DITA projects: “simple” and “complex” Key messages and themes: Creating scalable DITA projects Simple project details Complex project details TinyWeb demo server Lessons learned For more information

Key Messages and Themes Creating scalable DITA projects

March 2007implementingDITA™: Setting the Stage4 Key Messages Increased complexity can result in both: - A significant increase in benefits - A significant increase in challenges Take the time to architect and plan well at the simple stage, so your more complex projects are “elegantly sophisticated,” not “a complex mess of spaghetti-docs.”

March 2007implementingDITA™: Setting the Stage5 Themes: Architecture and Content Benefits of complexity: sophistication! –Higher quality content –Opportunities for content reuse, collaboration, and customization –Opportunities for content integration and reuse (for example, documentation and training material) Challenges of complexity –Need for tight, centralized control and close collaboration

March 2007implementingDITA™: Setting the Stage6 Themes: Technology, Logistics Benefits of complexity: sophistication! –Faster response time –Tighter integration with product and related software (e.g., translation memory) –Ultimately cheaper Challenges of complexity –Technical complexity can increase beyond a typical writer’s comprehension –Potential loss of control of the process and tool choice –Significant start-up costs (time and $)

Simple Project DITA Open Toolkit User Guide

March 2007implementingDITA™: Setting the Stage8 Doc Ant build script XML source file (messages content) XSLT stylesheet for “dynamic” DITA source file XHTML, HTML Help, PDF output Static DITA source files (all other content) “Dynamic” DITA source files (messages content) Source DITA source Content output Xalan or SAXON Simple Project 2 Disconnected Processes DITA Open Toolkit 1i 1p 1o 2p 2i 2p 2o 2i i = input p = process o = output Command-line script 1p

March 2007implementingDITA™: Setting the Stage9 Simple Project Overview –Title: DITA Open Toolkit User Guide –Collaborative effort: Anna van Raaphorst (content specialist) and Dick Johnson (technology specialist) –Volunteer contribution to the DITA community Document profile –Bookmap specialization (demo level) –20 chapters –300 topics –Publishing targets: XHTML, HTML Help, PDF Publishing history –August 2006 (Toolkit 1.2.2) –October 2006 (Toolkit 1.3.0) –(Planned) Early April 2007 (Toolkit 1.3.1)

March 2007implementingDITA™: Setting the Stage10 Simple Project (continued) Contents –Basic concepts –Getting started –Getting information –Evaluating DITA and DITA Open Toolkit –DITA use cases –Installing, upgrading –Plug-ins –Setting up your working environment –Processing and publishing to all 9 target environments –Troubleshooting the build process –Creating topics and maps, sample files –Linking, accessing, reusing, customizing, specializing, localizing (translating), managing, distributing, migrating –Sample files –FAQs –Release information –DITA core vocabulary (controlled vocabulary, glossary)

March 2007implementingDITA™: Setting the Stage11 Simple Project (continued) Changes/additions to April 2007 edition –Significant restructuring –Basic concepts –Localization (translation) –Content reuse –Building from within Eclipse –Building Eclipse Information Centers –Eclipse XMLBuddy editor –Processing overview –Publishing to XHTML using a frameset

March 2007implementingDITA™: Setting the Stage12 Simple Project (continued) Features, benefits –“Vanilla” DITA –Core vocabulary Defines the project and product (Toolkit) Content reuse –Sample projects and processing scripts Grocery shopping Garage –PHP-based tools for debugging and reporting (available free) –Dynamic generation of Toolkit messages files –Advice based on collaborative, real-world experience

March 2007implementingDITA™: Setting the Stage13 Simple Project (continued) Challenges –Content organization, architecture –Technical learning curve –Collaboration With subject-matter experts Among team members –Content integrity (establishing, maintaining) –Strategic thinking and planning (today’s solution must scale up to tomorrow’s!)

Simple Project Set-up

March 2007implementingDITA™: Setting the Stage15 Directory Structure (overview) Toolkit, User Guide, and sample files User Guide output files Output files produced by PHP debugging and reporting tools

March 2007implementingDITA™: Setting the Stage16 Directory Structure (source) continued

March 2007implementingDITA™: Setting the Stage17 Debugging and Reporting Tools

March 2007implementingDITA™: Setting the Stage18 “Conditionalization”

March 2007implementingDITA™: Setting the Stage19 Core Vocabulary (reuse)

Complex Project Set of documents built within the product

March 2007implementingDITA™: Setting the Stage21 Complex Project: Product Skytide Analytical Platform ( OLAP tool: “Enables the analysis of nonrelational data using traditional Business Intelligence techniques without requiring transformation of the data into relational format” XML-based (written in Java) Consists of Designer, Server, and SDK Works with DB2 9 (Viper) Can do business analytics and content analytics

March 2007implementingDITA™: Setting the Stage22 Complex Project: Documentation Titles –Getting Started (GS) –Administration Guide (AG) –Modeling Guide (MG) –Future: Developer Guide (DG) Formal content reuse –Common files conref’ed between topics –Installation instructions (GS and AG) –Images (All) –Glossary (core vocabulary) (All) –Introduction (doc descriptions, target audience) (All) –Object properties (All)

March 2007implementingDITA™: Setting the Stage23 Complex Project: Doc (continued) Target publishing environments –XHTML –PDF –JavaDoc reference material –Future: Context-sensitive help (on object properties) Specialization: Bookmap Customization (ditaval) –Windows/UNIX –PDF/non-PDF

March 2007implementingDITA™: Setting the Stage24 Complex Project: Doc (continued) Processing reuse –Three-tier build process: (1) product build.xml (2) generic doc build.xml (3) separate Ant script for each doc –Can build a complete release package (including docs) any time –Doc “unit test” takes place outside the top-level product build Informal content reuse –Shared content between documentation and training material –Estimated savings: 50-75%, 2 days to formalize 2-day training class

March 2007implementingDITA™: Setting the Stage25 Product files: (1).class files (a) properties repository (array of strings) (b) other class files (2).jar file Main Ant build script (build.xml) Doc Ant build script (doc/build.xml) XML source file (properties content) Java source file(s) XSLT stylesheets - For dynamic Java source file - For dynamic DITA file Java compiler JavaDoc output (properties) XHTML output PDF output (properties, other) Static DITA source files (all other content) Dynamic DITA source files (properties content) Used 3 times: (A) JavaDoc (B) Props repository (C) dita2xhtml, dita2pdf Source DITA source Content output Xalan or SAXON DITA OT B A C JDoc compiler Complex Project 5 Sequential Processes 1i 1o 2p 2o 3p 3i 4i 3o 1-5p 4o 1&4p 5p 5o 1i 2i4i 5i i = input p = process o = output

March 2007implementingDITA™: Setting the Stage26 Directory Structure

TinyWeb Server Details and Demo Created to illustrate the complex project

March 2007implementingDITA™: Setting the Stage28 TinyWeb Server Product: Very simple web server that displays photos of Australia and NZ Documentation –Input: XML file of error messages –Output (1): Product error messages displayed when runtime errors occur –Output (2): JavaDoc –Output (3): Dynamic DITA file that is merged with static DITA files to produce XHTML output

March 2007implementingDITA™: Setting the Stage29 TinyWeb product files: (1).class files (a) messages repository (array of strings) (b) other class files (2).jar file Main Ant build script (build.xml) Doc Ant build script (doc/build.xml) XML source file (properties content) Java source file(s) Java compiler XHTML output (messages, other) Static DITA source files (all other content) Dynamic DITA source files (messages content) Source DITA source Content output DITA OT TinyWeb Project i = input p = process o = output XSLT stylesheets - For dynamic Java source file - For dynamic DITA file 12 See directory structure (next slide) JavaDoc output (messages) JDoc compiler

March 2007implementingDITA™: Setting the Stage30 Directory Structure DirectoryContents binJava compiler output files buildProduct.jar files docDITA source/output files, Ant script javadocJavaDoc output master_ant_scriptsMaster Ant build script srcJava source files website_testSample website for project server xmlProject metadata file xslXSLT stylesheets (DITA, Java code) See diagram (prior slide)

March 2007implementingDITA™: Setting the Stage31 XML Message Definitions

March 2007implementingDITA™: Setting the Stage32 Dynamic Java Source

March 2007implementingDITA™: Setting the Stage33 Dynamic DITA Source

March 2007implementingDITA™: Setting the Stage34 Generated PDF Output

March 2007implementingDITA™: Setting the Stage35 Generated JavaDoc

March 2007implementingDITA™: Setting the Stage36 Server Startup Messages

March 2007implementingDITA™: Setting the Stage37 Server Log Messages

Lessons Learned The importance of “setting the stage”

March 2007implementingDITA™: Setting the Stage39 Lessons Learned Do at least two simple prototypes before tackling a complex project First prototype (3-4 weeks) –All new content (concepts, tasks, reference topics) –At least 2 output targets –2 tiers –Up to 50 topics –1-3 people (one being an information architect and one who is technology savvy) Second prototype (6-8 weeks) –Some new, and some migrated content –Focus on reuse, customization, specialization, linking strategies –3 tiers –Up to 100+ topics –4-6 people (one architect, one technologist, one editor)

March 2007implementingDITA™: Setting the Stage40 Lessons Learned (continued) Apply the lessons learned doing your simple projects to set the stage for your subsequent complex projects Enjoy your future successes!

March 2007implementingDITA™: Setting the Stage41 For More Information Anna and Dick’s professional website: DITA Open Toolkit User Guide: Or: These slides and TinyWeb server package: We welcome comments and suggestions!

implementingDITA™ Setting the stage: Creating simple DITA projects that will scale up (Last Slide) VR Communications, Inc.