What is Technical Writing

In 20 words or fewer
Technical writing is creating documents that help someone install, deploy, configure or use a product or a service.

In 50 words or fewer
Technical writing is creating documents that help someone install, deploy, configure or use a product or a service. It results in the creation of things such as user manuals, admin guides, instruction booklets and help systems, but not of business proposals, white papers, case studies, and so on.

In 100 words or fewer
Technical writing is creating documents that help someone install, deploy, configure or use a product or a service. It results in the creation of things such as user manuals, admin guides, instruction booklets and help systems, but not of business proposals, white papers, case studies, and so on. However, the distinction between technical writing deliverables and general business deliverables is getting increasingly blurred. These days, technical writers are also called upon to create or edit marketing collaterals, press releases, internal training tutorials, computer-based training material, and so on.

The Covering Letter

I had already been working for more than 10 years when, in 2006, I switched to the technical writing field. The first job was fairly easy to find - I looked up the vacancies, found a few that I liked the look of, got a call for an interview, and got onboarded It was a fun, learning experience at that company. Two years later, I thought it was time for me to change jobs. That shouldn’t be too difficult, I told myself, since I am now “experienced”. Two months later, I realised that though I was getting responses to my applications, they were not really from companies that I was dying to work for. The “hey-I’d-love-this-job” vacancies that I had applied to weren’t generating responses. I gave a long and hard look at my résumé (though this blog post is not about that). I also gave a long and hard look at my covering letter. My English teacher in school had taught me that all non-letters (CVs, forms, cheques and drafts, etc.) MUST be accompanied by a covering letter, so my standard practice thus far had been something on the lines of:

So, I re-read this letter critically. “Yew”, I told myself. “Hiring managers of “hot companies” must be getting tons of these. What can I do to make my covering letter interesting enough to make them click that link that takes them to my actual résumé?”

I thought awhile and came up with a different covering letter. This is what I want to share with all of you in this blog post of mine. The covering letter that I finally sent out got me three interview calls within the space of an hour, and all of them from three “good” companies. I am at one of them today . This is what my edited covering letter looked like.

It may be a totally unconventional manner of doing things but I realise that it made me stand out from the crowd and still get taken seriously.

Money Matters (spot all nouns)

This blog post appeared in a slightly different form in TechCraft, a once-in-two-months e-zine distributed to the members of the yahoo group technical_writers_india. To subscribe to this group, send an email to technical_writers_india-subscribe@yahoogroups.com

---

Money matters.
What does the phrase mean? Does it refer to the matters related to money (money, n.; matters, n)? Or does it mean that having some money really does matter (money, n.; matter, vb)? Is matter a noun or a verb?
Phrases such as these are potentially confusing, not only to readers in English but also to translators who translate such disjointed, disconnected phrases that appear in the user-assistance deliverables that we as techwriters create. In today's globalised economy, where the bigger of the multinational companies earn a significant portion of their revenue from outside their home country, we need to be careful about what we document. Why? Because, in all likelihood, what we document is going to be translated into 10 different languages, if not more. When we write in English, if we could keep the following points in mind, it makes life a lot simpler for translators. Trust me :) I used to handle localisation projects (before I decided that I'd rather write the very source that gets localised).

(1) Write short sentences

Writing short sentences is the equivalent of speaking slowly. A sentence that is long-winded has to be read more than once to be understood. A translator works under deadlines, and re-reading stuff takes away that much of the translator's time. Consider the following sentence:

The YST server ensures that all hosting servers of a YST product or service always sync with each other with respect to product versions of the services hosted by them.

Phew!

(2) Do not use compound nouns that have more than two words

Compound nouns with more than two words are potentially ambiguous (see the title of this post). Consider the following sentence:

The ABC file configuration program was not installed on this computer.

I can have the following three interpretations of this sentence:

• The configuration program of ABC file was not installed on this computer.
• The program of file configuration of ABC was not installed on this computer.
• The program, called ABC, of file configuration was not installed on this computer.

If clarity requires a few more words, use them. If you cannot avoid using three- or four-word noun phrases, use hyphenation to remove potential ambiguity. Consider the following revision:

The ABC file-configuration program was not installed on this computer.

Sounds better?

(3) Do not begin a heading with a verb

Consider the following sentence:

Print the Expense Summary

Are you telling a reader to go ahead and print the expense summary (in which case the heading's fine) or are you trying to tell a reader how to print an expense summary. If it's the latter, do add a "How to..." at the beginning of the heading - it orients the reader to your think-track.

Again, consider the following sentence:

Printing the Expense Summary

Do you mean that you (or the printer) is at this moment printing the expense summary or do you want to describe the process of printing the expense summary?

(4) Do not embed text in images

Else, it will take that much more time to do the following:

1. Extract the source text from the image.
2. Create a duplicate image minus the text.
3. Insert the translated text back into the image.

Or, if you cannot avoid doing so, be aware of the extra effort needed to localise the images.

(5) Do not expect the translators to be familiar with all sorts of content-authoring tools

You may have Vista-equipped workstations that run Structured FrameMaker, which integrates seamlessly into Webworks to produce beautifully compiled help-files. Your documents may be stored as XML modules. But do not expect all translators to have all the software that your company uses or to be familiar with XML and HTML tags. You have the following possible solutions:

• Send across the source text in a format that is editable by the majority (examples: Notepad, Word, Excel) and budget for the effort needed to rework the translation in the format that you want.
• Pay the translator for software that the translator may have to buy to cater to your special needs, and train the translator to use that software
• Look for a translator who can handle the file formats that you use.

Each of these options has a cost-time trade-off that you have to evaluate.

(6) Share your glossary with the translator

In other words, speak the same language. If you think that "trend graph" plots more than one Y against time X and your translator thinks that "trend graph" is a graph that shows the change of one Y against time X, then we are not speaking the same lingo.

Similarly, if you have a terminology in the target language, share it with the translator.

(7) Provide for text expansion and contraction

Be aware that translations to other languages may take up more space or less space than the source English text. Arrange your page layout and document layout to accommodate the variation. This may be important if your manual gets packed in the same carton as the software, and suddenly you find that the document is bulkier or larger than you what you planned.

The same holds true for UI elements. If you can have a say in the UI design, arrange the buttons and captions in such a manner that expansion and contraction of text is taken care of.

(8) Be available to answer queries

Make that extra effort to reach out to a team you've never seen, and probably never even spoken to. Your translators may be scattered over the globe, working in a time-zone different from yours, and they may not be subject matter experts. They may often stumble upon words and phrases that are not clear to them. Budget for time-zone differences and let the translators know when they can expect a response to their queries. Remember that translators are as much pressurised by deadlines as you are and their output is directly dependent on the feedback they get from you.

I am sure there are more points, but these are the ones that I think can take care of a lot many things.