Writing English documents the "proper" way

While working on internal Hyper-V documentation I wrote over 200 pages of content (mostly technical). I got some reviews by Rob Dendtler (thx Rob!), and the most interesting things I learned from him were not technical, but tips regarding writing style. The two common mistakes I made (and they are common in general as I learned):

  • Using second person instead of third.
  • Using passive voice instead of active too often.
    • Example of passive voice: “There are several ways in which VMM and Hyper-V can move a virtual machine depending on the underlying storage infrastructure and technologies.”
    • The same sentence in active voice (sounding way better): “VMM and Hyper-V move Virtual Machines in many ways, depending on the storage infrastructure and technologies.”
    • So why active voice is better? Active voice seems to be more action-oriented and generally needs less words to describe the same. Which means it is easier to read. Of course there are some uses of passive voice, but people writing documents tend to abuse the passive voice (and the same happened with me).
    • More details on this: http://www.dailywritingtips.com/passive-vs-active-voice/

Remembering those two rules, can make your documents more objective and clear. At least that helped me a lot.

Advertisements

~ by alipka on July 2, 2008.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

 
%d bloggers like this: