Andrzej's "IT Thoughts" Weblog

Loose thoughts about IT management&operations

Writing English documents the "proper" way

Writing English documents the "proper" way

  • Comments 2
  • Likes

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.

Comments
  • Don't forget proper spellings and pronunciations as we're talking writing proper English e.g.

    colour not color

    centre not center

    "rooter" not "rowter"

    "water" not "warter"

    and countless others ;-)

    Thing is being English having to do this "translation" can at times be almost like talking a second language (after typing Center as in "System Center" so many times I've found myself misspelling  the UK English word "centre" on more than one occasion)

  • Cliff - you are right, however most of the time I am using US English (since that this the English I learned) but I guess it depends on the audience or country. I am not to judge whether UK English is more "proper" then US English;)

    I know my remarks are only a subset of many guidelines, but they should refer to both UK and US English.

    Anyway I got some info from Blake Handler (http://bhandler.spaces.live.com):

    "I'm sure you already know about this feature -- but it would be a great time to mention the "Active / Passive" Grammar Checker feature within Microsoft Office.

    http://office.microsoft.com/en-us/word/HP101477121033.aspx"

    Maybe it will help out as well. I haven't used it before though.

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment