Author Max: Great DITA, Great Documentation

Bookmaps enable users to organize their DITA information into front matter, parts, chapters, and back matter. Typically, publications are created from a bookmap while DITA maps are used for simpler documents, or to group topics for reference from a book map or from another DITA map.

Referring to DITA maps from a book map or from another DITA map provides a great way for grouping topics. Refer to the DITA map in the bookmap whenever you want to include the collection of topics in the bookmap.

Tip: You can still use a DITA map to group topics when slight variations in the map are required (such as a topic describing how to use a feature applies to variant A of the product but not to variant B of the product.) Apply conditions to the topic references in the DITA map (such as “gram-negative”) and when the map is published (for example, for “gram-positive”), topics can be filtered out by condition.

You can nest topics under a parent topic. Using a parent topic rather than a <topichead> element enables you to easily add a short description or context information to the collection to topics.

Nested task topics are especially useful when a procedure divides into individual tasks.  You can nest the subtasks under a concept topic or under a task topic.

Tip: If the subtasks need to performed in a particular order, set the collection-type attribute for the parent topic to sequence. 

For publications that have two or more very different kinds of information, use <part> to divide a document’s chapters into logical groupings.

Example: In a document that contains both procedures and reference information, you can define two parts, one containing the how-to procedures and the other containing the reference  information.

Tip: The best practice, in general, is to reference a DITA map from the &lt;part&gt; element. This allows easy reuse of the  collection of topics, and allows editing of the DITA map for the part in parallel to editing of the bookmap.

In the <chapter> element of a bookmap, should you refer to a specific topic or to a DITA map?  Our vote is squarely on the side of referencing a DITA map.

Referencing a DITA map from the <chapter> element enables allows easy reuse of the collection of topics in the chapter, and allows editing of the DITA map for the chapter in parallel to editing of the bookmap.

In this example the<chapter> element references a DITA map:
<codeblock><chapter href=”intro.ditamap” format=”ditamap”/></codeblock>

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>).

Writers are conditioned to using tables.

Get past it. Table invite endless tampering with settings for column width.  In most cases, get over it and get past it.  Go for <dl>, definition lists.

The key point here is “most cases”. Most, but not all. If it’s absolutely critical that you display content (such as images and descriptive text side-by-side, and you don’t want to configure <dl> so that <dt> and <dd> display side-by-side in general, or if you absolutely must have a number of columns, then go for tables.

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.