DITA Writing Tips

– Anindita Basu

DITA is about semantic tags. This means all content must be placed within tags that explain the purpose of the content. Thus, for example, a UI element is tagged with the <uicontrol> tag (and not with <b> as we’re wont to do in HTML) and a directory location is tagged with the <filepath> location rather than a formatting tag that goes < font face = courier, size = …>. What tags can be used while wiritng in DITA is governed by its DTD. We, as writers, don’t change the DTD but write within its framework. When we write in DITA, we do not worry about formatting – how a tag is rendered in the output is governed by its stylesheets (which, again, we as writers rarely ever modify). All we worry about is whether that which we’re writing is being placed within the correct DITA tags.

To me, this was godsent because it freed me from worrying about the presentation of content and left me free to do what I like doing best – write. But when I first started writing in DITA, I stumbled a couple of times – sometimes to find the right allowable tag for my content, at other times to enhance the presentation by adding a caption or removing a link when these could not be done with whatever tag I was using. In this article, I share with you the workarounds I found for some of those early writing problems.

• To conref dissimilar elements, wrap the source text in <ph>
• To prevent all topics of a <reltable> row from linking back to each other, do not use the CTR format
• To include pretty much anything in a <step>, insert an <info>
• To preserve the formatting of a copy-pasted text snippet, use <pre>
• To have your topic show different titles in different scenarios, use <titlealts>
• To caption your images, use <fig> as container for <image>
• To have a slightly longer <shortdesc>, put it in an <abstract>

To conref dissimilar elements, wrap the source text in a <ph> tag

DITA is about content reuse. Any chunk of text, down to a single word, can be written once and called several times. There’s a rider however. Only like can call like. I cannot, for example, reuse a <step> as an <li> – if I want to reuse the text of a <step>, I can conref it only from another <step>. This becomes a bit of a hassle – say, I have written something in a <shortdesc> in a concept topic that makes perfect sense as the <context> of a task topic, how do I conref it? By using the <ph> tag.

Code at the point of the source text. Assume the file name is file1.dita

<shortdesc>
	<ph id = "textTOconref">When you set up the reporting system,
            you are setting up two separate entities: a blah and a blah blah.
            This is the text that will be reused through a conref</ph>
</shortdesc>

Code at the point of conref

<context>
	<ph conref="file1.dita#textToconref"> </ph>
</context>

A <ph> tag can be inserted almost anywhere, and, more important, can contain pretty much anything – even an image.

To prevent all topics of a relationship table linking back to each other, do not use the CTR format

The relationship tables in DITA are an extremely useful tool for maintaining, at a single point, the linking between all topics in a book. When I use relationship tables, I do not put the “See Also” links in the topics themselves but in this table where each row denotes a relationship between topics named in that row. The authoring tool I use at work is set to default to the CTR format of relationship tables, which means it’s a three-column table with a column each for concept (C), task (T), and reference (R) topics; each row in the table represents a discrete relationship and all files in a row link back to each other. So far, so good but sometimes I end up with more links than I really want.

Of the seven links, only two are needed for the topic (it’s on licenses, right?) but there are four other links, generated because those tasks needs licenses as a prerequisite (footnote). I lived with that awful clutter till I discovered another type of relationship tables – the two-column type, where one column contains source files and the other target files, and the <topicref> tags are qualified with either a sourceonly attribute or a targetonly attribute. When a <topicref> has a sourceonly attribute, a link is generated to the target topic only in the source topic; when it’s targetonly, a link is generated to the source topic only in the target topic. Thus I unclutter my topics by creating one-way links between them.

To include pretty much anything in a <step> tag, use an <info> tag

When describing procedures, sometimes it becomes necessary to include things such as pictures, code snippets, explanatory notes, and so on. But a <step> tag can contain only a <cmd> tag and then a bunch of other tags that are pretty useless for pictures, notes, and code. The workaround is to insert an <info> tag after the closing <cmd>; an <info> tag can contain pretty much anything.

<step>
	<cmd>At the command prompt, set the JAVA_HOME variable to point
             to the installation directory of the Java development kit.</cmd>
		<info>
			<codeblock>
			set JAVA_HOME=<JDK_installation_directory>\Java\jdk1.6.0_18
			</codeblock>
		</info>
</step>

Better still, an <info> tag can be placed pretty much anywhere.

To preserve the formatting of a copy-pasted text snippet, use <pre>

Because DITA is XML, anything enclosed within < > is interpreted as a tag. However, if I need to include something like this in my doc, what do I do?

<preference
	name = "the key of the preference"
	value = "the value of the preference to be set">
</preference>

I wrap the text in a <pre> tag, just like I’d have done if I were writing it in HTML. With the <pre> tag, not only can I use the angular brackets but also preserve the spaces and the line breaks.

To have your topic show different titles in different scenarios, use <titlealts>

The <title> tag of DITA has more than one use: not only does it show up as the first heading on a topic, but also as the topic heading in the Table of Contents, and in the result page of a search query. But what makes perfect sense as a topic title on the topic page that has stuff written on it might seem out of context in a search result page. Look at this picture (footnote) and tell me if the titles tell you anything at all – whether you should click-through to a topic or skip?

I use <titlealts>, with which I can specify two additional titles: a <navtitle>, which shows up in the ToC pane, and a <searchtitle>, which shows up in the search results page. I make these two titles slightly more verbose than the actual page title, so that they make sense even when seen outside the context of the page content.

<title>Installing</title>
<titlealts>
	<navtitle>Installing the small package<navtitle>
	<search>Installing the small package on Windows systems:
                High-level steps<searchtitle>
</titlealts>

In the absence of a <titlealts> tag, the title displayed in the ToC and in the search result page defaults to what’s contained in the <title> tag.

To caption your images, use <fig> as container for <image>

The easiest way to put an image in a topic is by using an <image> tag. But, according to the DITA language specification, an <image> tag cannot contain anything other than alt text. How do I caption my images? By wrapping the <image> tag in a <fig> tag, which can contain not only a <title> tag but a host of other useful ones such as <desc>, <note>, and <codeblock>.

To have a slightly longer <shortdesc>, put it in an <abstract>

The <shortdesc> element is what I use for writing the “pull text” for the topic – the text that shows up in search results and in hovertext for links, and thus is a deciding factor for user click-through to that topic. Mostly, my short descriptions contain 2-3 sentences that sum up the topic. But sometimes, just sometimes, I feel the need to write a longer short description. I’d still like to retain the shorter short description as the pull text, but what if I want to add another two sentences and want to have them all in that section itself – the first section on a page – instead of carrying the extra sentences over to the body of the topic (where they’ll probably have to reside after a <prereq> and, thus, lose all sense of connect)? In such a case, I use an <abstract> tag (footnote), like this:

<abstract>
<shortdesc>You can automatically install the adapters to an existing instance
        of WebSphere Application Server, automatically install a new
        instance of WebSphere Application Server and then automatically install
        the adapters on the new instance, or manually deploy the adapter files
        on WebSphere Application Server.</shortdesc>
If you choose the manual deployment method, after the installation is over
you must deploy the data service Web archive files to an existing WebSphere
Applicaton Server and then add the adapter plug-ins to the Web application.
These steps are not needed in the automatic installation option.
</abstract>

---

Footnotes

1. DTD stands for Document Type Definition. It defines what tags and tag attributes are used in a markup language, where those tags should appear, and which tags can be contained by other tags. To borrow from the musical metaphor of Hindustani classical, a DTD is like a raag’s aroh, avaroh, and permitted notes where, for example, a Pancham must always be followed by a Shudha Nishad which, in turn, can only be followed by a Shudh Dhaivat.
2. About the “Related links” example: It’s okay if I show that doc snippet as a bad example of a reltable. I wrote the doc.
3. About the search results picture page: It’s okay again. That’s my doc – my editor was very sweet while pointing out it rendered no one any help whatsoever and was next to useless.
4. The <abstract> element was introduced in DITA 1.1 but the language specifications page still does not list it. For information on the <abstract> element, click here.

---

About the author:

Anindita Basu is an information developer at IBM, the company that sowed the DITA seed and continues to nurture it. She blogs at Writing Technically and can be reached through an email.

About the illustration:

The image is used with permission from Mallika Yelandur.

All product names, logos, and any trademarks used in the illustrations and elsewhere in this article are for identification purpose only, are the property of their owners, and their rights are acknowledged.