Author Max: Great DITA, Great Documentation

Like many great questions, the answer to “how small is too small for conditional content” is – it depends.

This post will consider just one factor that determines how small is too small: translation.  If the content will be translated, then translations will face difficulty if just one or two words are marked as conditional.  This is true because adjacent words or phrases need to change when the text changes. When switching to a language where adjectives have masculine and feminine variants or when moving between languages where word order changes in a sentence, having too small a unit for conditional content will create huge problems.

Consider the following example, simplified for clarity: a product is available in separate models for boys and for girls,   and the content was marked as green <condition=girl>girls</condition><condition=boy>boys</condition>. When translating  to French, the writer needs to change “green girls” to “les filles vertes”, and translate “green boys” to “garçons verts” but since “green” is outside the bounds of the condition, translation tools will break down.

The bottom line is that while good things come in small packages in jewelery, smaller is not always better in DITA.

Good Things Come in Small Packages, But Not Always in DITA

Image credit: Fotografiert von Mario Sarto 04. Februar 2004 (GNU Free Documentation License)

Topics, taken alone, are generally just part of larger units of information.  To organize your topics meaningfully, you can:

• arrange topics into chapters and parts in the bookmap,
• group topics in DITA maps, and
• nest child topics under parent topics (sometimes called super topics, super tasks, or chapter maps).
• nest topics under topic headings

In the coming posts we will describe at least some of these strategies.

Embedding multiple topics inside one topic file (polygamous topics) is not good practice. The golden rule is one topic, one idea.

How to identify polygamous topics? Markers for this phenomenon are use of <title> more than once in a topic.  If you have more than one <title> in a topic, with the obvious exception of titles for images or tables, you are almost certainly embedding multiple topics inside one topic file.

What should you do? Take the content under each <title> or under each <section> and include in a separate topic.

Why use <choices> or <choicetables> instead of <ol> or <ul> in a task topic when you need to choose what to do next?

The benefit is that the markup is semantic! When you use <choices> or <choicetables>, the machine (and the writer!) understands explicitly if we are talking about:

1. <choices> where the customer has reached a decision point and must choose one of the options (such as,  take Route 66 to Boston or Route 81 to Ithaca).
   or
2. <choicetable> — where the customer has different options to get to the same result (such as CTRL+S or File > Save).

Using <ol> or <ul> eliminates semantic markup! Using <choices> or <choicetables> explicitly indicates the kind of juncture the reader has reached — and forces the writer to state if no matter what the choice, the end result will be the same (<choicetable>), or if the choice selected will lead to a different outcome (<choices>).

To describe what you can do, or what options are available, use a reference topic.

A good rule of thumb is that users tend to need, and prefer, step-by-step procedures in task topics to more general reference information.

As an an example, consider the case where a user can customize display of information in a window.  You could provide one or more reference topics that describe available options for sorting, grouping and filtering.  Or, more effectively, you would provide task topics for each procecure.  Such as:

• Sort columns alphanumerically
• Group by columns
• Filter information so you only see what is applicable to you
• Save the view you have set up

You might want to insert the topics in your ditamap as child topics under a topichead or under a concept topic such as “Custom Controls for Your View”.

The urge to describe everything would be, in this case, counterproductive and decidely non-minimalist.  Adding a reference topic here would create more content to update/maintain over time and add to your translation bill.  So, resist the temptation to add more reference content.  Often, when tempeted by a reference topic, Just Say No.