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)

The buzz about how breakthroughs in genomics will drive personalized medicine got us thinking about how personalized is your practice’s digital presence.  If we expect – at some point – that personalized medicine will drive improved clinical outcomes, shouldn’t we expect that personalizing your digital presence to individual patient needs will drive better business performance for your practice?

When you visit the web site for Amazon or get email from an on-line merchant, the content that you see is personalized based on what the vendor knows about you and about your needs.  When a patient gets an email from you, shouldn’t that content be personalized based on what the patient has expressed interested in (e.g., cosmetic procedures or nutritional counseling or…)?  We think so. Go for it!

This is a break from our DITA postings, but we need to share with you a really cool site that we had a key role in upgrading.  When PRS-Med asked for help in getting content into shape for their web site overhaul, we rolled up our Joomla sleeves and got to work.  Check out the site at PRS-Med and let us know what you think!

Using different DITA maps or book maps you can assemble different publications from the same set of topics.  Using conditions on topic references (<topicref>) from maps you can include a topic conditionally.   As noted in post #12 in The DITA Project, topicrefs can be included or excluded based on conditions applied to the topicref.

In many cases, however, you will want to include the same topic in different publications, but have slightly different content in each publication.  Of course, if the content was very different it would — often — make sense to have separate topics.

The easiest way to reuse a topic with slight variations is by applying conditions to the topic that will vary in each publication.

For example, you could change a description for what happens when an antibiotic reaches the outer cell wall for a gram-negative organism by applying the condition ”gram-negative” to the sentence.  You might have another sentence with a description for what happens when an antibiotic reaches the outer cell wall for a gram-postitive organism by applying the condition ”gram-positive” to the sentence.

Future posts will consider:

• when to use the keyref mechanism rather than conditions,
• using conditions in a conref and
• how small conditional content building blocks should be.

This is a break from the latest posts about markup, but if you’re going to do DITA, you should also be able to figure out what it’s costing your company.  I posted a presentation about estimating costs and benefits from implementing a DITA solution when you face uncertainty.  Forecasting under uncertainty is a fact of life for most of us. Uncertainty about:

• how many products will be documented
• frequency of updates
• percentage of reuse
• translations (if any)

Looking forward to your feedback on the presentation!

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>