Writing tips

Focus on your user (not the product feature)

The goal of the reader is to accomplish a certain task; using your product for that task is of secondary importance. Show the user how to do that task or tell the user why the task should be done.

See these examples and decide for yourself which one you would have preferred had you been the user.

Example I

Option 1

[Page title] Using the Connection Manager wizard

Option 2

[Page title] Connecting an XML data source to an ETL catalog

Example II

Option 1

The product supports single sign-on framework, which is implemented through form-based authentication and caching of login credentials.

Option 2

To log in without having to enter your login credentials each time, use the single sign-on authentication feature.

OR

The single sign-on authentication feature can be used to cache your login credentials so that you do not need to enter them every time.

Do not use phrasal verbs (if just the verb would suffice)

Phrasal verbs can be difficult to understand by readers whose first language is not English. Such verbs can also be difficult to translate. If the same meaning can be conveyed by using only the verb, cut the preposition out from the phrase.

Phrasal verbs	Alternate verbs
Click on	Click
Print out	Print
Zip up	Compress
Start up	Start
Comment out	Comment out

Relate the unfamiliar to the familiar (when introducing something that’s new for your readers)

Example 1

In baseball, the pitcher throws the ball straight at the batter.

Example 1, reworked

In baseball, the pitcher throws the ball straight at the batter unlike in cricket where a bowler can bounce the ball on the pitch before it reaches the batsman.

Example 2

In Central Repository System, teams share and integrate their ongoing work in branches.

Example 2, reworked

In Central Repository System, teams share and integrate their ongoing work in branches. Think of a branch as a shared work area that can be updated at any time by team members.

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.

Acknowledgments

The “About the author” is the outcome of a crowdsourcing experiment; it’s a mash-up of part of the contributions of Samartha Vashishtha and Sarala Prakash.