Lesson 1: What is Technical Writing?
The importance of word choice and consistent writing
A good technical writer not only understands his intended audience, he understands the importance of clear and concise writing. Although most writers dream of beautiful prose that can move readers to another plane of existence, technical writing is all about removing any possible ambiguities so the reader understands precisely what to do. Short descriptive active sentences are generally better than long flowery lines filled with metaphor. Word choice is paramount to a technical writer. If there is any possible way an instruction can be misread or misconstrued someone will do so. When possible consequences of wrong actions are data corruption and data loss it becomes very important that users understand what you are telling them to do.
Consistency is also important. If you lead your users to expect all functions to appear in boldface followed by a set of parentheses, then make sure all functions appear that way. Otherwise, your readers may not realize that they're all functions and could get confused. Similarly, keep a similar style and vocabulary throughout each document. If you're writing an introduction filled with very general and basic conceptual material make sure you avoid as much technical terminology as possible and that you always define all terminology you do use. If several writers are collaborating on the same document make sure that individual voice doesn't shine through. When the document is finished you should not be able to tell where one person stopped and another picked up. You shouldn't even be able to tell that more than one person worked on the document.
