Thursday, October 13, 2016

73 Words - Is Technical Writing a Dying Art?

As a Technologist, I rely on technical writing for my training, product evaluation and selection. When I see a video describing a new technology, I skip to the text.

Reasons to skip the video?

  • The video is bound to simplify the important details that are fundamental building blocks in any product.
  • The video is produced by marketing people, who all too often do not understand the product.
  • If I am coming to you for information, I already have specific questions to answer about how your product will work in my business environment.
  • I can read the text much faster and skip to the important parts rather than watch the video.

How can marketers and educators help me?

  • Focus on the text.
  • Hire technical writers.
  • Focus on the technology.
  • Eliminate "market-speak", a technical manual is not a place to blather on about innovation.
  • Avoid appropriating terms from other technologies that have a similar meaning.
  • Write declarative sentences.

Example: "Introduction to Microsoft Windows Server 2016" Microsoft Books


73 words, one period. A bit of a bad cut and paste job there in the middle: "software-defined datacenter features that can were born in..." I am glad they didn’t use the phrase “legacy” anywhere in this run-on sentence! "Legacy" describes me pretty well...

Anyone who survived the 90's in technology remembers Buzzword Bingo so here's a shot on that sentence/paragraph:


Market-speak Buzzwords “Self-Improvement”
Pillars Security Are clear about
Commitment Software-defined datacenter Choice
Platform of choice On-premises Now-exist
Frameworks Application platform Necessary
Traditional applications Application Allow
Azure Cloud Prepare