Alan DITA best practices

Alan HouserPrincipal Consultant and Trainer

Tel: [email protected]

DITA Best Practices

Group Wellesley, Inc.

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 Communication

Know your audience!

Best Practice #1: Start with careful analysis of your audience and tasks

Many 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 Task Analysis

Persona

• 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 Task Analysis

Task Analysis: One Technique

Card 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 Reuse

Tip: 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 Reuse

Tip: 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 Minimalist Principles

• Roots of DITA: minimalist approach


Tip: 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.


Stem Sentences

Changing your battery

To change your battery, you should do the following:

1. Remove the cover.

2. Remove the battery.


Stem Sentences

Changing your battery

1. Remove the cover.

2. Remove the battery.


Tip: 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 editorial quality control

A 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, put aside legacy content

It 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 reusable content chunks

Tip: Maintain boilerplate text and variable string replacements in special-purpose topics.

Examples:

• Admonishments (notes, cautions, warnings)

• Legal text

• Variable string substitution


Tip: 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.


Tip: Use DITA conrefs or conkeyrefs to maintain variable text.

Tip: Use DITA filtering attributes to control replacement text.


Tip: 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 to contact us:

Alan [email protected]

Group Wellesley, Inc.933 Wellesley RoadPittsburgh, PA 15206USA412-363-3481www.groupwellesley.com

mailto:[email protected]

http://www.groupwellesley.com/

Technology

Alan DITA best practices