I am an experienced software engineer of many a year. I subscribe and read MSDN magazine, I also read many of the popular technical programming and design books on the shelves. In comparison, it is always an interesting change spending the day reading and updating professional documentation, written by software engineers (who do not write for public media). In most cases, there is an apparent distinction between the grammars in each scenario. Many of us tend to write the way we speak, which can often lead to very informal and difficult to read text.
I am not an English major by any means, and I rely heavily on the tools to perform spell and grammar checking for the words I write. I especially lean on the help provided by the grammar checker in Microsoft Word. Before writing any new documentation, I make sure that I crank up the grammar settings so that Word can catch any misnomers in my English. By default, Word does not check the style of your documentation, which includes checking for passive voice errors.
Changing the writing style from “Grammar” to “Grammar & Style” in the Word Grammar will put Word on steroids, and all of a sudden, your document will show more green than the moldy piece of cheese left in your refrigerator for the last 6 months. Word will now underline all the grammar errors that affect the reading style, including passive voice and split infinitives.
Why is passive voice so important?
In short, passive voice makes a document hard to read because passive sentences are often wordy, do not always define the subject in context, and often leave the reader with ambiguity.
The following sentence is an example of passive voice:
“Log files are typically opened and closed on a daily basis.”
The presence of the “are” in the sentence makes the sentence passive. The following, less wordy, sentence is revision of the one above, and uses active voice:
“Typically, log files open and close daily.”
When writing professional documents, such as those documenting software engineering concepts, it is important that the content by clear, concise, and easy to read. Active Voice assists the reader of a document by presenting an alert, personal, and demanding spin on the wording. Writing professional documentation is different to writing a post on your weblog; professional documentation should convey a clear understanding of subject matter by the writer and enable the reader to gain a similar depth of knowledge on the subject.
When writing your document, be aware of the following words in your sentences, because they signify the passive voice:
*is
*is being
*were
*was
*are
*has been
*have been
*had been
*should be
Articulating in text software engineering concepts is no easy task (ask anyone who has written a technical book), but the tools are there to help you. Next time you need to publish a document to your peers or project-working group, why not look at the passive voice content in your document – you will receive a lot more praise from your readers if you convert your document to active voice.