dita everyday by tom rathkamp [email protected] [email protected]
TRANSCRIPT
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?
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
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.
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
DITA Basic StructureTopics
(concept, task, reference)
Elements(body, step, note,
etc.)
Attributes(audience, chunk,
product, etc.)
Elements represent types of content that commonly occur in technical documentation. There are “container” elements and “content” elements.
Topics represent general types of information that commonly occur in technical documentation.
Attributes are used to alter the behavior or condition of topic content, depending on the situation or need.
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.
DITA Transformations (output)
• XHTML
• HTML Help
• Web Help
• Eclipse Help
• Java Help
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 – discussionMy recommendations
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.
Reuse basics – the mantra of DITA
• Author once, use many times• Topic reuse (within same or different map)• Content reuse (conref )
DEMO
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
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
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.
Create topics
• <concept>, <task>, and <reference>• Main elements• Container elements vs. content elements
Create maps
• DITA map vs. bookmap• Topic references• Processing attributes (ex. print and toc)• collection-type attribute• linking attribute
Generate output with DITA-enabled tool (Oxygen)
• Generate PDF and CHM from same map file• Make copy of shipped transformation type (Oxygen)
Conditional processing
• Ditaval file basics• Conditionalize topics in Map file• Uses attributes
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
Relationship tables
• Related topics in Help system• Easier to track cross linking• Main benefit - links don’t live in topic files
Simple customization
• Don’t modify shipped DITA files• custom.xsl• DITA plugins
Toggling between WYSIWIG and Code view
• DITA everyday workflow• All about comfortability and familiarity
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.
Sources• Online
http://dita-ot.sourceforge.net/
http://tech.dir.groups.yahoo.com/group/dita-users/?v=1&t=directory&ch=web&pub=groups&sec=dir&slk=1
http://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
• Books
Introduction to DITA – A User Guide to the Darwin Information Typing Architectureby Jennifer Linton and Kylene Bruski
DITA for Practitioners by Eliot Kimber
Several books on XML and XSL