Technical Writing Tips 1

Using boldface in procedures

In procedures, if something appears due to the user action, it can be shown in the regular font because the very fact that it appears with the said name makes it identifiable for the user. But, when an action is to be executed, it is required that the user is directed to the UI, and the command button and location are shown in bold. Or, you can even show the location of the command button in regular font but the command button must be in bold. Accordingly, we can stick to one of the following uses:

Case 1: All the UI elements are in bold

From the Automation menu, click the Analog Recording option. The Recording window appears.

Case 2: Only the location of the command button and the command button is in bold

From the Automation menu, click the Analog Recording option. The Recording window appears.

Case 3: Only the command button is bold

From the Automation menu, click the Analog Recording option. The Recording window appears.

The point is to be consistent.

That vs. which

That is used for restrictive clause. By restrictive we mean something that limits the meaning. It is not separated by comma.

For example: A suitcase that has lost its handle is useless. And, not A suitcase, which has lost its handle, is useless.Another example: Our team, which was working during weekends, is on a holiday. Here, which was working during weekends is used in the non-restrictive sense. Even if you remove it, the meaning does not change. It is similar to providing information in parenthesis.

In technical writing, we avoid which because that hints that the information can be glossed over without loss of comprehension. One, we do not want to provide information that is not pertinent. Two, we do not want the user to ignore any bit of information we provide. All that can be introduced using which can be explained separately in a sentence. Especially in procedures which is avoidable.

Select vs. click

Select does not initiate any action. At the most, the selected area may appear grey. Click initiates an action.

the user, user, or a user

We avoid using ‘the’ before father, aunt, cook, nurse, and so on when they refer to our own people. For example, ‘Father is home’. And, not ‘The father is home’. So, if the users comprise a limited group of known individuals, dropping the is fine. But, we usually do not encounter such a situation.

Some examples of phrases from MSTP that do not take an article: rights of user, details of user.

‘The user’ implies the user of a given application. For example: A car met with an accident. The driver was rushed to the nearest hospital. Although driver is used for the first time, still he is indirectly identified as the driver of the car.

As for using ‘a user’, we are making a general reference and keeping our user base open. This is less preferred over ‘the user’.’

So, we either avoid ‘the’ completely or use it everywhere. But, where user qualifies another noun such as the user interface, the user details (unless it is a compound word such as user rights) it takes ‘the’ before it.

Capitalization

Sentence case: Capitalization of first word, proper nouns and other words specified by English rules

Title case: Capitalization of all words except articles, prepositions, conjunctions, and to be forms (be, am, is, was, are, were, been, being)

Title case is used for titles. From Heading 1 onwards, sentence case is preferred (at least in publication).

etc.

The abbreviation etc. is always preceded by a comma even if only a single term comes before it.

Repetition in a series

An article or a preposition applying to all the members of a series must either be used only before the first term or else be repeated before each term.

Example: In spring, summer, or winter (In spring, in summer, or in winter)

(Source: Originally posted at Cybage DoXperts, Cybage documentation team blog.)