Writing Tips

Ensure that the first sentence summarizes the content of the topic

When your topic gets pulled in to a search results page, the first sentence is often displayed along with the link to your topic. Make it apparent, upfront, what the topic contains instead of having someone click the link, land on the page, and discover it to be not relevant.

Avoid self-referential constructions such as these:

Installing the databases

This topic explains how to install the DB2 database.

Working with the Resource Wizard utility

This chapter explains how to use the Resource Wizard utility.

Instead, summarise what the topic contains:

Installing the databases

Log in as a user of the SYSADM_GROUP specified at the DB2 instance level, and run the parameters.bat file.

Working with the Resource Wizard utility

Embed images and videos in your files by using the Resource Wizard utility, which automatically inserts the <object> tag parameters that are required for the embedded file.

Ensure that every topic has at least one related link

The topic might not be what someone was looking for but one of the links within the topic might point to the desired information. Topics without related links are like dead ends with no signage – frustrating. In-topic links are important because, in a ‘search anything’ world, the Home page is not the only entry point to the help system; each page is an entry point.

Use non-restrictive clauses sparingly

In eternal confusion between ‘that’ and ‘which’, a missing comma or an incorrectly used word can change the meaning of a sentence. Use non-restrictive clauses (or, parenthetical information) sparingly. If you really must include parenthetical information, consider rephrasing the text to shorter, simpler sentences. Also, non-restrictive clauses at the end of the sentence are difficult to translate – they need more time, effort, and alertness than do short, simple sentences.

About the author

Anindita Basu works as an editor for IBM and lives with her parents in Allahabad, India. She is a DITA believer and is currently writing a book on the subject. She has keen interest in Indian mythology, culture, and film music.  She can be reached at anindita_basu@shortmail.com.