The spectrum of technical writing


I am often asked what is the difference between writing a blog post and an article that’s published in a magazine such as Windows IT Pro. In response, I think that a spectrum of technical writing exists that goes something like this:

  • The most basic (and often very useful) contribution that people make is in an online forum such as the TechNet forum for Exchange 2010. While many forums have moderators to keep everyone focused on the topic on hand, few exert much quality control over the contributions. You therefore accept whatever information you glean from these sites on face value. You might recognize a contributor, in which case you’d assign a greater import to the content, but many contributions are repetitive, recycle information from elsewhere, or are just plain wrong.
  • Blogs represent the next level up in the spectrum. A blog is a very personal expression of someone’s opinion on a topic. Hopefully, if it’s a technology topic, the author will do some research before they post. This happens in good blogs and you can see the quality of the material when it does happen. However, it’s important to remember that humans are fallible and that the content of very few blogs are reviewed from an editorial or technical perspective. The most notable exception is provided by blogs written by product teams such as the Exchange development group, where I have every reason to believe that posts are carefully scrutinized before publication. This doesn’t imply that mistakes don’t happen; it just means that mistakes occur less often because many eyes have probably looked content over before it appears in public.
  • Magazine articles, at least those published by reputable companies, represent the next level. Articles differ from blog posts from development teams because they are usually independent and therefore don’t include the same kind of Kool-Aid content that invariably sneaks in when someone working for a development group discusses their product. Articles are similar to blog posts from development groups because they go through an editorial cycle intended to improve the flow and content of the article and to eliminate obvious mistakes before publication. The better the magazine, the more work they put into the editorial cycle – this is one of the primary factors that attracted me to write for Windows NT Magazine (the predecessor of Windows IT Pro). To give you an insight, before Windows IT Pro publishes an article, it will be edited by a copy editor and reviewed at least once by a technical reviewer, who is responsible for the technical accuracy of the material. Content that isn’t quite on the money may also be looked at by a separate reviewer. In addition, article submissions that come into the magazine are often looked at by contributing editors to check that the level of content will be attractive to readers and is aligned with the kind of material that the magazine publishes. The point here is that good publishing teams take extraordinary care to ensure that compelling technical content appears in their magazine.
  • White papers are usually generated by technology vendors, often in an attempt to explain the finer details of how their products work. These documents are usually worth perusing as they contain all manner of detail that may not be available elsewhere. And while white papers do receive a great deal of editorial attention as they are drafted and prepared for publication, some are afflicted by the need to pay attention to the paymaster. In other words, if a company sponsors a white paper, the author may not possess full freedom to express their true opinion about the technology. Good companies allow authors the independence of their thoughts (often because the company’s technology is pretty good) whereas not-so-good companies put out white papers that are pretty dark and useful only when serving as bin liners.
  • Books represent the outer limit of my technical writing spectrum. These are usually the work of a single author (writing good technical books in a team is very difficult and often a recipe to end friendship) and take many months to produce. My Exchange 2010 Inside Out book spans 400,000 words and took me 15 months to write. It is unsurpassed as a door stop or aid to sleep. Books require a huge amount of help from series editors, copy editors, technical reviewers, indexers, artists, and other professionals to get the job done. And while books allow authors the undoubted luxury of being able to cover topics in-depth, the sad facts are that a) content starts to age as soon as you write it and will be outdated by service packs and new releases and b) you’ll always leave out something that someone is interested in.

The spectrum of technical writing evolves over time. I’m sure that some would consider Twitter as a viable medium and there will be new ways to communicate that evolve in the future. e-Books that can be quickly developed and revised to keep the content aligned with the current state of technology is definitely a promising platform for the future that may lead to the demise of printed books.

Then again, this is a blog post so it’s personal, could be full of mistakes, and is highly open to debate (see description above).

– Tony

Microsoft Exchange Server 2010 Inside Out is also available at Amazon.co.uk and a Kindle edition. Other e-book formats for the book are available from the O’Reilly web site. Alternatively, to listen to over 18 hours (not including the labs) of detailed technical information about Exchange 2010 over three days, come along to the Exchange 2010 Maestro Seminars that will run in San Diego (May), London (June), and Greenwich, CT (October).

Advertisements

About Tony Redmond ("Thoughts of an Idle Mind")

Exchange MVP, author, and rugby referee
This entry was posted in Technology, Writing and tagged , , . Bookmark the permalink.

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