1 / 42

implementingDITA™

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. www.vrcommunications.com Revised: March 29, 2007. Contents.

alvaro
Download Presentation

implementingDITA™

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. 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. www.vrcommunications.com Revised: March 29, 2007

  2. 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 implementingDITA™: Setting the Stage

  3. Key Messages and Themes Creating scalable DITA projects

  4. 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.” Key Messages implementingDITA™: Setting the Stage

  5. 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 implementingDITA™: Setting the Stage

  6. 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 $) implementingDITA™: Setting the Stage

  7. Simple Project DITA Open Toolkit User Guide

  8. 1i 1i SimpleProject 2 Disconnected Processes XSLT stylesheet for “dynamic” DITA source file XML source file (messages content) 1p 2p 1p Command-line script Source Xalan orSAXON Doc Ant build script DITA Open Toolkit DITA source Content output 2i 1o Static DITA source files (all other content) “Dynamic” DITA source files (messages content) 2i i = inputp = processo = output 2p 2o XHTML, HTML Help, PDF output implementingDITA™: Setting the Stage

  9. 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) implementingDITA™: Setting the Stage

  10. 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) implementingDITA™: Setting the Stage

  11. 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 implementingDITA™: Setting the Stage

  12. 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 implementingDITA™: Setting the Stage

  13. 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!) implementingDITA™: Setting the Stage

  14. Simple Project Set-up

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

  16. continued continued Directory Structure (source) implementingDITA™: Setting the Stage

  17. Debugging and Reporting Tools implementingDITA™: Setting the Stage

  18. “Conditionalization” implementingDITA™: Setting the Stage

  19. Core Vocabulary (reuse) implementingDITA™: Setting the Stage

  20. Complex Project Set of documents built within the product

  21. Complex Project: Product • Skytide Analytical Platform (www.skytide.com) • 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 implementingDITA™: Setting the Stage

  22. 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) implementingDITA™: Setting the Stage

  23. 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 implementingDITA™: Setting the Stage

  24. 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 implementingDITA™: Setting the Stage

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

  26. Directory Structure implementingDITA™: Setting the Stage

  27. TinyWeb Server Details and Demo Created to illustrate the complex project

  28. 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 implementingDITA™: Setting the Stage

  29. XSLT stylesheets - For dynamic Javasource file - For dynamic DITAfile XML source file (properties content) 1 2 3 Java source file(s) See directory structure(next slide) Source 4 TinyWebProject Main Ant build script (build.xml) DITA source 5 Content output 5 Dynamic DITA source files (messages content) Doc Ant build script (doc/build.xml) Java compiler JDoc compiler Static DITA source files (all other content) i = inputp = processo = output DITA OT TinyWeb product files: (1) .class files (a) messages repository (array of strings) (b) other class files (2) .jar file 7 6 8 JavaDoc output(messages) XHTML output (messages, other) implementingDITA™: Setting the Stage

  30. 6 Directory Contents bin Java compiler output files build Product .jar files doc DITA source/output files, Ant script javadoc JavaDoc output master_ant_scripts Master Ant build script src Java source files website_test Sample website for project server xml Project metadata file xsl XSLT stylesheets (DITA, Java code) 5 8 7 4 3 1 See diagram (prior slide) 2 Directory Structure implementingDITA™: Setting the Stage

  31. XML Message Definitions implementingDITA™: Setting the Stage

  32. Dynamic Java Source implementingDITA™: Setting the Stage

  33. Dynamic DITA Source implementingDITA™: Setting the Stage

  34. Generated PDF Output implementingDITA™: Setting the Stage

  35. Generated JavaDoc implementingDITA™: Setting the Stage

  36. Server Startup Messages implementingDITA™: Setting the Stage

  37. Server Log Messages implementingDITA™: Setting the Stage

  38. Lessons Learned The importance of “setting the stage”

  39. 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) implementingDITA™: Setting the Stage

  40. Lessons Learned (continued) • Apply the lessons learned doing your simple projects to set the stage for your subsequent complex projects • Enjoy your future successes! implementingDITA™: Setting the Stage

  41. For More Information Anna and Dick’s professional website: www.vrcommunications.com DITA Open Toolkit User Guide: www.vrcommunications.com/resources Or: http://dita-ot.sourceforge.net/SourceForgeFiles/doc/user_guide.html These slides and TinyWeb server package: www.vrcommunications.com/resources We welcome comments and suggestions! implementingDITA™: Setting the Stage

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

More Related