DITA Everyday by Tom Rathkamp thomas_rathkamp@yahoo.com

1. DITA Everydayby Tom Rathkampthomas_rathkamp@yahoo.com

2. Agenda What is DITA? Why DITA? Why NOT DITA? DITA Basic Structure Topics and Maps DITA Transformations (output) DITA-Enabled Tools Summary Raw DITA vs. DITA-enabled tools Re-use basics – the mantra of DITA DEMO Postlude: Transitioning to DITA Questions?

3. What is DITA? • DITA (Darwin Information Typing Architecture) is a topic-based XML framework used to support the authoring, management, and publication of technical documentation. • Contains a core set of information types: concept, task, reference. • Content is separate from format • DITA consists of two main files: topics and maps

4. Why DITA? • Align with software development processes • Reduces the cost of maintaining and updating information • Reuses information quickly and efficiently across multiple deliverables • Technology is open, not proprietary and inaccessible. • Why I decided to make to take the plunge.

5. Why NOT DITA? • Authoring and technical learning curve • Minimal deliverables for non-diverse audiences • DITA-enabled tools are constantly catching up • Legacy content – time permitting

6. DITA Basic Structure Topics represent general types of information that commonly occur in technical documentation. Elements represent types of content that commonly occur in technical documentation. There are “container” elements and “content” elements. Attributes are used to alter the behavior or condition of topic content, depending on the situation or need.

7. Topics and Maps • Topics house specific content of a distinct type. • Maps collect topics to achieve deliverables. • <concept> - answers the question “what is”? Provides summary or background information. • <task> - essential building block for providing procedural information. • <reference> - layout highly structured data for quick reference, such as a command reference . • Other non-core topics include machinery, glossary and so on. • Topic files contain .dita file extension. • Map files contain .ditamap file extension.

8. DITA Transformations (output) • PDF • XHTML • HTML Help • Web Help • Eclipse Help • Java Help

9. DITA-Enabled Tools Summary • Adobe FrameMaker (plus DITA-FMx plugin) • Oxygen XML Author • Madcap Flare • Arbortext Editor • Others • Supporting CMS’s – Xdocs, SiberSafe, Iixia, Componize The challenge with overlap – discussion My recommendations

10. Raw DITA vs. DITA-enabled tools • Get a DITA-enabled tool !! • Learn raw DITA first, even if using a DITA-enabled tool. • For DITA-enabled tool, locate embedded DITA-OT.

11. Reuse basics – the mantra of DITA • Author once, use many times • Topic reuse (within same or different map) • Content reuse (conref )

12. DEMO

13. Demo Agenda • Download and set up the DITA Open Toolkit • Review and edit DITA build files • Generate output from the command line • Create topics • Create maps • Generate output with DITA-enabled tool (Oxygen) • Conditional processing • Content reference (conref) • Relationship tables • Simple customization • Toggling between WYSIWIG and Code view

14. Download and set up the DITA Open Toolkit • http://dita-ot.sourceforge.net/ • Recommended: DITA-OT1.6.1_full_easy_install_bin • Extract contents of ZIP file • Download and install Apache ANT and FOP, Java Development Kit, and Saxon XSLT processor, and JavaHelp . • Set up environment variables • DITA specification

15. Review and edit DITA build files • About Ant - Apache Ant is a Java library and command-line tool whose mission is to drive processes described in build files as targets and extension points dependent upon each other.  • Build files set parameters, determine files to transform, and output folder location. • Use startcmd.bat file to set environment.

16. Create topics • <concept>, <task>, and <reference> • Main elements • Container elements vs. content elements

17. Create maps • DITA map vs. bookmap • Topic references • Processing attributes (ex. print and toc) • collection-type attribute • linking attribute

18. Generate output with DITA-enabled tool (Oxygen) • Generate PDF and CHM from same map file • Make copy of shipped transformation type (Oxygen)

19. Conditional processing • Ditaval file basics • Conditionalize topics in Map file • Uses attributes

20. Content references (conref) • Chunks of repeated content for multiple topic • Reused content must work in the new context • New context must reference filename and ID attribute of reused content • conref=“file.dita#resusedcontent/elementID“ • Conref overkill

21. Relationship tables • Related topics in Help system • Easier to track cross linking • Main benefit - links don’t live in topic files

22. Simple customization • Don’t modify shipped DITA files • custom.xsl • DITA plugins

23. Toggling between WYSIWIG and Code view • DITA everyday workflow • All about comfortability and familiarity

24. Postlude: Transitioning to DITA • Four components of transition:- Management - Writers - Tools - Content • Start with small pilot project • Isolate the project from your real work. • Perform a content audit. • Develop a strategy for converting unstructured legacy content.

25. Questions?thomas_rathkamp@yahoo.com

26. Sources • Onlinehttp://dita-ot.sourceforge.net/http://tech.dir.groups.yahoo.com/group/dita-users/?v=1&t=directory&ch=web&pub=groups&sec=dir&slk=1http://www.ibm.com/developerworks/xml/library/x-dita1/http://ant.apache.org/http://www.xiruss.org/tutorials/dita-specialization/https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita • BooksIntroduction to DITA– A User Guide to the Darwin Information Typing Architecture by Jennifer Linton and KyleneBruskiDITA for Practitioners by Eliot KimberSeveral books on XML and XSL