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.
  • Example of second person: "When you use Hyper-v to create a Virtual Machine, you ..."
  • Example of third person: "When using hyper-v to create a Virtual Machine, ... "
  • Third person is more formal and objective
  • More details on this: https://www.cliffsnotes.com/WileyCDA/Section/What-are-the-first-person-second-person-and-third-person-points-of-view-Which-is-used-for-formal-essays-.id-305408,articleId-7622.html
• 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: https://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

• Anonymous
  July 02, 2008
  The comment has been removed
• Anonymous
  July 03, 2008
  The comment has been removed