DITA Best Practices Alan Houser Principal Consultant and Trainer Tel: 412-363-3481 email@example.com Group Wellesley, Inc. www.groupwellesley.com
About Me• Consultant and Trainer in Publishing Tools and Technologies• Member OASIS DITA Technical Committee• Society for Technical Communication, Liaison to the World Wide Web Consortium (W3C)• Fellow, Society for Technical Communication• Candidate for Vice President, Society for Technical Communication, 2011-2012
DITA in Context• Developed by IBM corporation as a successor/replacement for IBMIDDoc (a “book-centric” information model).• Donated by IBM to OASIS (Organization for the Advancement of Structured Information Standards).• DITA 1.0 finalized by DITA Technical Committee February 2005, formally approved by OASIS June 2005.• DITA 1.1 approved by OASIS August 2007.• DITA 1.2 approved by OASIS December 2011.
Best Practices for Discussion• Start with audience and task analysis• Write for re-use• Embrace minimalist principles• Include human editorial control in your workflow• Use best practices when migrating legacy content• Manage boilerplate content and string replacement values
First Rule of Technical Communication???
First Rule of Technical CommunicationKnow your audience!
Best Practice #1: Start with carefulanalysis of your audience and tasksMany people are first exposed to DITA through the standard topic types of task, concept, and reference. They are tempted to begin by writing topics.Any DITA scenario should begin with a careful audience and task analysis.Formalize the analysis in a DITA map.Then write topics to populate the map.
Techniques for Audience and TaskAnalysisPersona• Short description of a typical reader.• Can be several sentences, typically a paragraph or two.• Your audience is probably not “anybody”, even if you think it is.• For most products and services, 3 – 5 personas are sufficient
Example Persona John is a an administrator at a regional hospital. He has 2 years of college, and is proficient with Microsoft Office products. Once/month, he uses the Acme2010 Audit Software to generate a report of hospital bed usage. He does not use Acme2010 Audit Software at any other time, for any other task.
Techniques for Audience and TaskAnalysisTask Analysis: One TechniqueCard sorting• “Brainstorm” to discover typical user tasks.• Write each task on a note card.• Sort the note cards. Categories should reveal themselves.• Use the cards to define your topics.• Use the categories and organization to define your map.
Best Practice #2: Write for ReuseTip: Omit details except when necessary, especially when details may vary across related products.Examples:Remove the five cover screws.Remove the cover screws.Enter your password on the backlit keyboard.Enter your password.Press the green button to start a call.
Best Practice #2: Write for ReuseTip: Avoid inline cross-references. Use DITA relationship tables to generate list of related topics.Example:Learn about video in Playing Video on your Cell Phone.What if you generate content for a model that does not support video? The link is broken or suppressed.Learn about video in .
Best Practice #3: Embrace MinimalistPrinciples• Roots of DITA: minimalist approach
Best Practice #3: Embrace MinimalistPrinciplesTip: A DITA topic should express a single idea, and be usable stand-alone.Tip: DITA does not support stem sentences. They are considered unnecessary in topic-oriented publishing.
Best Practice #3: Embrace MinimalistPrinciplesStem SentencesChanging your batteryTo change your battery, you should do the following:1. Remove the cover.2. Remove the battery.
Best Practice #3: Embrace MinimalistPrinciplesStem SentencesChanging your battery1. Remove the cover.2. Remove the battery.
Best Practice #3: Embrace MinimalistPrinciplesTip: Use the DITA <shortdesc> element to describe your topic, to aid user navigation and improve findability.The <shortdesc> element appears after the <title> and before the <body> content. It is considered both content and metadata. It should be a short (1-2 sentence) description of the topic.The <shortdesc> text is rendered as preview and hover- over text.
Best Practice #4: Don’t forget editorialquality controlA well-defined quality-control process becomes even more important in the context of distributed topic-oriented authoring. Be sure to include the review of human editors and reviewers in your workflow.
Best Practice #5: When starting, putaside legacy contentIt is natural to want to begin a DITA migration by converting legacy content to DITA.If you take this approach, the result is the same legacy content, with only a subset of DITA benefits.Go to your legacy content only after you have completed an audience and task analysis, and have developed your DITA information architecture.
Best Practice #6: Manage reusablecontent chunksTip: Maintain boilerplate text and variable string replacements in special-purpose topics.Examples:• Admonishments (notes, cautions, warnings)• Legal text• Variable string substitution
Best Practice #6: Manage reusablecontent chunksTip: DITA referencing, inclusion, and linking is based on <filename> and <id>. Unlike most XML-based publishing architectures, <id> values need not be unique across document sets. Use this feature to label reusable chunks of content.
Best Practice #6: Manage reusablecontent chunksTip: Use DITA conrefs or conkeyrefs to maintain variable text.Tip: Use DITA filtering attributes to control replacement text.
Best Practice #6: Manage reusablecontent chunksTip: Use DITA 1.2 keyrefs to ease maintainability of references (conrefs, topicrefs) and improve the authoring experience.<ph conref=“reusableText/variables_nokia.xml#Brand” /><ph conref=“Phone/Brand” />
Contact Us!We hope you enjoyed this presentation. Please feel free tocontact us:Alan Houserarh@groupwellesley.comGroup Wellesley, Inc.933 Wellesley RoadPittsburgh, PA 15206USA412-363-3481www.groupwellesley.com