Technical Writing Tips 2

check that vs. check whether

Check that implies the ellipted sense to make sure. It actually means check (to make sure) that. It is used when the author or the user is sure of what to expect.

Check whether means check (to see) whether (or not). The author or user is not sure of what to expect.

Example: The CheckProperty command checks whether the actual value of the specified object property matches the specified expected value.

en dash (Alt + 0150)

en dash is used to indicate a range of numbers including dates, scores, and pages in a document. It is used in the sense of 'to'. Also, Pune–Narsapur Express.

It is used to hyphenate compounds of compounds, where at least one pair is already hyphenated. Example: open-source–based browser  

Respective and respectively

Respectively is an adverb meaning  'in the given order'. It comes at the end of the sentence and is preceded by a comma.

Correct: Tim and Tom wrote the admin guide and the release notes, respectively.

Incorrect: Tim and Tom logged on to their computers, respectively.

Correct: Tim and Tom logged on to their respective computers.

Respective is an adjective meaning 'particular' or 'separate'.

Should have

Should have refers to past events that did not happen or a promise that was not kept.

So, in a user guide that states the pre-requisites for the audience, the following statement would be incorrect.

Incorrect: The learner should have completed MTP-Basics.

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.)

Outsourcing

Branding one's products and services in a global economy cannot be achieved by mere indigenous effort. It has to be achieved by combining excellence from all quarters. This inevitability has to be turned to a positive advantage and all the major economies have already done that.

From the historical perspective, outsourcing is the longest stride in the amalgamation of economies and in bridging the gap between the developed and developing nations, for it speaks the language of mutual profit. And, IT has been the sweetest rhyme of the economic ethos.

Information Technology has set businesses sailing on the high seas of profit. The burgeoning share of outsourcing in the national income of developing countries and the developed nations increasingly favouring outsourcing amply speaks for it. People with capital are looking out for people with know-how. The ready supply of skilled man-power that can be deployed at any stage of the project is what makes the outsourcing companies look for talent offshore.

Companies are competing to establish industry benchmarks. But, their productivity tells them apart. Productivity is not just getting a job done at a lower cost; it is obtaining the best value for money. It is unwise to mistake it for short-term profits and forsake innovation.

From basic data entry, cross-selling, voice support to establishing captives that innovate, develop and maintain the projects for the outsourcing firm, outsourcing has come a long way. Sometimes the entire organizational function is located offshore. Regulations and policies are making more and more room to enable an easy transition of the business process.

The wage gap between nations has been another factor in business processes moving out to lower cost economies. The favorable currency exchange rates have shot up the disposable incomes of the developing nations and given impetus to measures adopted by governments and entrepreneurs to attract foreign nationals. Business is seen as a responsibility than as an opportunity by the developing nations. What better attitude could the outsourcer ask for!
(336 words)

Search Engine Optimisation

I am reading SEO book by Aaron Wall. Very comprehensive and, to an uninitiated such as me, it speaks a world. Juggling through the search algorithms, cautioning the practitioner about tweaking too much with the Web pages, emphasising time and again on the uniqueness of content and look, the book offers a lot of material to fortify the optimizer's traffic generating witchery.

The search engine optimizers are the head masons of the web world. They are employed to build an eye-catching Web page with the available resources. A house, with all embellishments, but lacking proper light and air soon wears a haunted look. A website owner runs a similar risk if his online presence lies in want of traffic and ranking. SEO provides an efficient outline, builds on it and also paves a broader driveway to the owner's Web page.

World Wide Web (WWW) has made it possible for you to reach out to the global audience hooked on the internet. Your web presence secures your place in the global information map. WWW is not a desolate road and nobody in there wants to build a hermitage for himself. People on web are seeking either involvement or business, and profit therefrom.

Your Web page is your marketeer. It has to be spruced up all the more because your Web page, in the end, has to warrant participation from the target audience, people who are the probable takers of what you have to offer. In doing so, you have the advantage of dealing with an informed readership that recognises your efforts at branding your product and service.

Branding is a global phenomenon and companies and businesses are vying against for customer attention. There are around 20 billion Web pages and Google has crawled about 10 billion of them (as of Dec 2007). Web, though it provides you an opportunity to represent yourself, is not obliged to generate traffic for you. There is a mechanisation called search engine that traces your location on Web sniffing for the key terms or keywords involved in the search. The early visibility in the search engine could place you in an advantageous position. And, SEO is all about improving your rank on the search engines and thus attract traffic for the Web page owner.
(379 words)