Writing Technically

Friday, May 7, 2010

DITA 1.2 - New <topic> elements

The DITA language specification v1.2 introduces two new topic elements: <bodydiv> and <sectiondiv>.
The <bodydiv> element is intended to be used as a grouping element for containing logical blocks of info that otherwise do not need either a title or a separate topic. It can be placed only within a <body> or within another <bodydiv>.
The <sectiondiv> element is similar to the <bodydiv> element except that it has more container elements - it can be placed within a <section>, <sectiondiv>, and a bunch of other tags depending upon the topic type.

Why and when should I use <bodydiv> and <sectiondiv>

If I want to reuse a whole group of info somewhere else, these two tags are handy. Not that such reuse couldn't have been done otherwise, but then, these tags can, for example, contain several <p> elements, some lists, some images...it's almost like being able to reuse an information chunk instead of individual tags. Without being actual formal topics, these tags behave like topics.

Related information

The <concept> topic type also has a new element in v1.2 that's similar to <bodydiv> and <sectiondiv>. It's called <conbodydiv>.

History of <topic> elements

Here's a list of the various topic elements from v 1.0 to 1.2:

DITA 1.0	DITA 1.1	DITA 1.2
dita	-	-
topic	topic	topic
title	title	title
titlealts	titlealts	titlealts
navtitle	navtitle	navtitle
searchtitle	searchtitle	searchtitle
-	abstract	abstract
shortdesc	shortdesc	shortdesc
body	body	body
-	-	bodydiv
section	section	section
-	-	sectiondiv
example	example	example
related-links	related-links	related-links

Friday, April 9, 2010

Writing in DITA - Tip # 3

While authoring, I often need to refer to that specific directory, that particular URL, this specific file which resides in this specific directory. As the software development cycle progresses, names change (and how). By the time people are ready for bit freeze, I am out of my mind worrying if all the specific references I put in your doc are updated (specific references are more "consumable" by a user). But if I've had the time to plan, I'd have probably envisaged such a scenario and prepared myself. How? I give here two alternatives (there could be more but I don't know of them yet). And, because I am making a case for Alternative 2, I'll shoot down each of the examples that I give for Alternative 1.

Alternative 1

Do not use specifics. Talk in generic terms. Examples:

From the Sun website, download the latest version of the Java Development Toolkit.
Problem: For all you know, Sun might be acquired by Moon, and the JDK be renamed to Lunar NetBeams.
In the installation directory of the software application, look for a file with a name that has a suffix that correspond to the product acronym as listed in the Offical Acronyms page of the software application.
problem: Which software application? You said Package A was prerequisite for Package B so I downloaded both from your website and installed them and they seem to be installed in the same directory - the directory name is the name of your company. Which subdirectory of the installation directory? There are no files in the main directory. Where is the Acronyms page? The first three hits in Google lead me to pages not maintained by your company.

Alternative 2

Use the conref facility provided by DITA.
DITA is about content reuse. We might as well rephrase that to say, "DITA is about reducing maintenance overheads". (<aside>The first sentence talks about a feature. The second about a benefit. Users look for benefits (what's in it for me), not features. Am a bit puzzled why so many techcomm people keep using the first sentence without, ah, repurposing it for the target audience.</aside>)

This is how I do it: I maintain a separate file called in which I have a bunch of text that I think are of a variable nature. Each chunk of reusable text is wrapped in a <ph> element and given an ID. Like this:

Then, in the main files, I just conref these <ph> chunks. The text comes out looking like this:

Pages