Author Max: Great DITA, Great Documentation

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.

Let’s say that you have a series of menu choices (such as Start > Programs > Accessories > Notepad).  Each menu choice item should be in its own <uicontrol> tag.  The whole series should be in a <menucascade> element.

A common error in preparing content is jamming multiple UI controls in one <uicontrol> tag, manually adding the connecting character (typically “>”).

Typical incorrect markup would be:

<menucascade><uicontrol>Start > Programs > Accessories > Notepad</uicontrol></menucascade>

The correct markup would be:

<menucascade><uicontrol>Start</uicontrol>
<uicontrol>Programs</uicontrol>
<uicontrol>Accessories</uicontrol>
<uicontrol>Notepad</uicontrol></menucascade>

When the content is published, the DITA OT adds connecting characters between the menu items to represent the menu cascade.  So, the output would look similar to Start > Programs > Accessories > Notepad.

Inspired by the movie Julie & Julia, here at Method M we have undertaken to emulate  Julie Powell, who cooks all 524 recipes from  Julia Child’s cookbook during a single year, a challenge she described on her popular blog.

So, we are off.  In 52 weeks we will try and post 104 examples of Do’s and Don’ts for DITA Markup.  No time to write more, we have to start preparing posts.  If you have suggestions that you want us to post, just go ahead and send them to us (info at methodm dot com).  We’ll be happy to credit you!

Stay tuned for the first postings soon.

DITA Thought for Today: one idea, one topic.

Just saw a procedure with mixed in in the prerequisites. An attempt to sneak in another procedure!

Tip for today: dividing your task topic into sections is usually a tip-off that your topic has more than one procedure.

Remember – one idea, one topic. (Kind of like, “one man, one vote”.)

GoMDweb.com continues to launch great new sites for dentists.

• Check out the  KJJ dental web site for a cool site with two languages.
• For a new site coming on line just now, check out Dacula Dental Associates.

We are very excited about bringing the benefits of our content publishing and lifecycle skills to health care, and contributing to improved caregiver-patient communication (and better outcomes!).

Ed Rabinowitz writes:

”Awhile back, you decided your practice needed to have a presence on the Web—a portal through which you could provide valuable information to your patients. You contracted with a website developer to launch such a site and populated it with items like the practice’s office hours, contact information, services provided, nice pictures of your building, and some biographical information on your staff. The problem, however, is that you did this five years ago, and little has been updated on the site since.”
For Ed’s full article, click here.

Indeed. In talking to physicians, dentists and other health care providers one of the most common refrains of small and mid size practices is:  ”we just don’t have time to update our practice web site”.  It’s a good point.  Without attention, content on the site grows stale and reflects poorly on the doctor. That’s why we like so much the commitment of Go MD Web to maintain the content and links in the health library and to provide updated articles for a range of specialties.