It used to be I could search on the Internet for documentation on most of the software I owned and find rough, but intelligible information on them. Documentation on known problems, recent enhancements, and tips on use were written as if spoken directly from the writer to me, as if in some sort of non-linear response to a direct question I had asked them. Over the past few years, however, documentation has become increasingly complex and lengthy. Instead of focusing on content, technical writers are becoming too caught up with style guides, legal disclaimers and beautifying previously useful information. Buried in this maze of red-herrings and boilerplate writings, necessary information has become all but lost.

This problem is compounded by the ever growing gap between useful information on the internet and e-junk. Michael Marien knew this as early as the late 90’s and noted:

The number-one negative is that having much more information is bad for our heads. It is bad because it produces infoglut, which may well be the greatest under-studied problem of our time.

Infoglut is not a static matter. It's been estimated in the Encyclopedia of the Future that scientific information doubles about every 12 years and general information doubles about every two and a half years. But the really good stuff, the most important knowledge that should steer society, communities, enterprises, and individual lives, is increasingly in short supply relative to other information devoted to entertainment and commercial interests. (Document 3 of 14)

What happened to being able to just post a document on the internet saying “I just found a problem in version 1.1 of the Acme Widget Maker where widgets come out sideways.” and leave it at that? Nowadays it’s more along the lines of “Acme would like to communicate an issue with it’s Widget Maker product that may or may not affect certain users in situations wherein widgets are designed to be created at certain angles …”; the necessary information is mired in fluff. Not to mention the fact that this information is buried in a document that’s buried deep in the Internet.

Still, documentation is a necessity. Virtually no technical product is in itself so self explanatory that it doesn’t require some written accompaniment.

Not all the blame lies on modern-day authors, the audience is just as responsible, if not more so. In a world where very little is taken at face value and every mistake is a lawsuit waiting to happen, authors and their editors have responded by wrapping their notes in wordy legal-ease, hold-harmless agreements and “as is” statements.

On the other hand, many readers of technical documentation would still rather count on notes straight from the engineer or other source of information, versus that which has been doctored by professional writers.

With all this in mind, we should take a step back and think about why we really need Technical Documentation. Technical Documentation conveys necessary product usage information, alerts product users of known issues and advertises new features.

Unfortunately, documentation often becomes mired in the techno-jargon or its parent company, legal ease surrounding the use of supporting information and other non-essential information. Style guides have become overly complex, providing larger and longer frameworks and extras often resulting in document templates actually being longer than the information being presented. In as much, it’s becoming rare to see abridged technical documents in any formal setting; instead they are left to newsgroups and other flooded peer groups.

So where do we go from here? How do we get back to the roots of Technical Documentation? In a study of online writing resources, Rehling stated in 1999:

Web design books are often tech tip manuals that emphasize visual presentation and are light rhetorically, with shallow treatment of planning and process, content selection, and usability. Books on online help (for example, Duffy, Palmer, and Mehlenbacher) and GUI design (for example, Zetie) often are more audience-sensitive and pragmatic, but are also limited by their treatment of a single form.

Where possible, outline long documents or provide a table of contents with links to other places in the documentation.

Possibly one of the most valuable tool may be providing technical documentation from the source in it’s raw format, if at all possible. In a bind, many readers would prefer to find an answer in the engineers own words, regardless of grammatical preciseness, as apposed to a longer, beautified document.

Establishing style guides and rough standards not just for professional writers but for the source of information, the technical professionals, is a must as well.

We Technical Writers, Support Professionals, Engineers and the like now have the responsibility and privilege of defining the new standard for online writing, and the future of a major portion of the internet. Moving forward always with the audience, consumers and customers in mind, we shall educate the world.

About the author
Jared Fredericksen
Lead Technical Support Analyst
BMC Software Certified Engineer – PATROL Central Architecture
BMC Software