Industry Standards

There are a number of standards used in the technical writing industry, ranging from simple word processor template sets that can be reused in corporate documentation guidelines, to complete document engineering standards that require substantial training to use effectively.

They are all based on one simple principle: the ability to effectively identify the problem domain (that which we want to document) and then break it down into pieces that can be logically grouped in order to create a structured final document. This is much like the mechanisms that are needed to perform software engineering, and so it is logical to assume that good software engineers can also make good document engineers and technical writers.

Unfortunately, where this connection falls down is in the realization of two basic differences between technical writers and software engineers or programmers. The first is that programmers are generally not very good at conveying complex ideas to a third party as a collection of simple ones. They assume that the reader has the same level of technical competence as they do, which is not necessarily going to be the case.

The second difference is that, unlike technical writers, programmers and software engineers do not enjoy writing documentation, since they would much rather be writing programs, designing complex systems, or debugging—anything other than writing documentation.

It is, however, easy to use software engineers in an informal workshop situation to help the technical writers to break down the problem domain and organize the general structure of the document that is to describe the system that needs to be put into place. It is basically the same set of skills, and much the same work needs to be done to engineer the system and to document it.

Even if the investment in a specific industry standard is deemed out of reach for the target organization, there are still basic principles that can be adhered to when creating documentation that revolve around psychological research, such as the fact that the human mind can deal with about five pieces of information in short-term memory at a time.

Thus, the document should be written in such a way that in order to understand a given key concept, it should not require the readers to hold more than five other concepts in their minds at once. These supporting concepts may be key, or they may be throwaway pieces of information that enable understanding but can be discarded almost immediately once the concept that they support is understood.

If one follows this theory to the letter, any system should be broken down such that it is comprised of five or less key concepts, each of which can be explained until comprehension by five or less supporting concepts, which, in turn, can be supported by five or less subsidiary concepts, and so on, through the system.

Another accepted principle of document construction is that no one idea should require more than a single page to express. Moreover, each page should only consist of a certain amount of text—techniques for cheating, such as reducing the font size to an almost unreadable 8 points, narrowing the margins, and removing header and footer information are all strictly forbidden.

The idea is that the coverage should not exceed one-third to one-half of the paper width, or three quarters of the available page height, after the printing margins are taken into account. The rest of the space is divided into four areas: the header and footer (which contain vital document information), a left-hand margin designed to contain labels for each concept and subconcept, and a right-hand margin that is wide enough for the reviewer to write notes in.

If these principles are borne in mind, the resulting document should be well thought out, easy to read and interpret, and communicate the information in a way that makes understanding less of a chore and more of a pleasant reading exercise.

0 0

Post a comment