Is your VCR programmed properly? Not sure? Maybe you couldn’t understand the directions in the manual.
VCR programming directions, camera manuals, tricycle assembly sheets — all are standing jokes in the technical writing community. One can reread these directions endlessly as you:
1. Stare into space and wait for inspiration, or;
2. Try holding your tongue differently.
All these tactics don’t help when the documentation is not usable. Just because you have spent a lot of money on something does not mean the documentation will help you operate, install, repair or use your purchase.
Documentation is not usable if it does not answer a specific question, information is presented in a confusing manner or information is incorrect.
The result is the documentation remains on the shelf and you flounder, using trial and error. Eventually you may get your VCR programmed or the tricycle assembled. But you leave the experience unhappy, disappointed, confused and thinking there must be a better way to do this task.
Now, think in terms of a disaster recovery plan - infinitely more expensive and important than a VCR programming feature. What can be done to help ensure your disaster recovery plan will have usable documentation? There is no single magic bullet. But the following nine steps address some of the most common documentation considerations.
Develop a good disaster recovery plan
You cannot expect documentation to make lucid a chaotic disaster recovery plan. A plan may be complex, but it must follow an internal logic. There must be a rational flow. When a disaster recovery plan is developed you cannot rely on documentation to make up for flawed organization. The best disaster recovery plan documentation is obtained when goals, methods and procedures, and desired results are clearly known.
Be prepared for documentation resource cuts
This is the inevitable money and time chase. When a disaster recovery plan runs into fiscal or time crunch, resources originally dedicated to documentation are usually used to balance the ledger. If the disaster recovery plan is over-budget, documentation funding may be cut. If the disaster recovery plan is overtime, the time may be taken from documentation effort.
This is not a fact to be bemoaned, it is a fact of corporate life. The question is, how to deal with it and still develop a usable document.
A way to deal with anticipated cuts is to develop a layered documentation plan. Plan for the documentation to consist of elements A, B, C, D and E. These elements can be, for example, a core documentation set (A), user guides (B), documentation subsets for certain parts of the organization (C, D, E), and so forth.
Give these elements a priority. If time and money is pulled, the least critical documentation elements are dropped to compensate. The goal is to protect the main project with adequate funds and sufficient time. If the entire disaster recovery project goes more smoothly than expected, the bells and whistles can be kept.
The key to this is to know:
- what is essential
- what is needed
- what is really nice and
- what would be handy
Then if needed you can start cutting back, but still end up with something valuable to the organization.
Know what you want the document to do
A disaster recovery plan can involve many players with many agendas. Training people may see an opportunity to develop a training document. Marketing people may see benefit in using the disaster recovery plan as a sales tool that indicates your organization’s commitment to uninterrupted service. Managers may see it as providing proof of need to superiors for increased funding or staffing.
It is an axiom that a document that tries to do too much does nothing. Yet the research that goes into developing a disaster recovery plan will have many uses. The urge will be strong to have many tangible uses for a document that, one hopes, will never be used for its primary goal — recovering from a disaster.
It is best if the disaster recovery document is used only for disaster recovery or disaster recovery training. Other separate documents should be created for the other stakeholders. In some cases, these subset documents may be literal copies of the disaster recovery document. Usually, however, the subset documents will have to be modified to suit the particular needs of marketing, training or other uses. This means increased cost and more time to produce these subsidiary documents.
All of this should be considered carefully when you start mapping out the disaster recovery documentation. But the goal should be that a given piece of documentation has one objective. If you try to force a document to do too much, you will have a document that confuses more than it clarifies.
Know your audience and write to it
Equally important as knowing what the document intent, is knowing who will read and use it. Know your audience and write to it.
A highly-technical organization will have its own jargon and preferred format. If using this jargon conveys the information, use it. Even if this is contrary to the general notion that jargon should be avoided. If that is the way your audience communicates, use that language. If your organization is less technically oriented, avoid jargon and take some effort to define terminology as you go along. As a guide, listen to the way members of your audience talk. This helps develop the tone of the document.
Determine access to the document before you write
Determining who will be able to read the disaster recovery document is another way of defining your audience, but it can raise some difficult issues.
If you talk to people involved in the disaster recovery plan, you will probably find them divided between two camps; those who favor as wide a distribution as possible for the documentation and those who favor quite restricted access. Both viewpoints have merit.
Those who favor broad distribution will say that in a time of crisis it will be necessary to marshall as many people as possible to recover operations. The more people who know about the disaster recovery plan, the better. In addition, if the plan is restricted to a few, those people may not be available to help implement the disaster recovery plan. No one else knows how to access it or understands the information it contains.
Those who favor restricted access argue a disaster recovery plan contains sensitive, proprietary company information. Security concerns mandate that only a few key individuals have access. Since these key individuals would be spearheading recovery anyway, broader distribution could lead to confusion. People could feel free to make their own interpretations about their role in the recovery.
It helps to resolve this access issue before the documentation is written. Duplication and distribution costs are dramatically affected if you know you need 10, 100, 1,000 or 10,000 copies of a given document.
Document the plan as it exists, not as it will be
Most disaster recovery plans are evolving creatures. It is very tempting to look down the road — knowing it will be several weeks or months before the plan is published — and think that by publication date such and such will be in place. Therefore, the document should take this into account now.
The argument for documenting what is still in the planning is that it will reduce document update costs and the document will be current when it comes out.
While this sounds good, virtually no equipment, policy or program works as expected. So you end up documenting an assumption as if it were a fact. When this proves to be inaccurate, even in a small detail, the credibility of the entire disaster recovery plan suffers.
Document the plan as it exists today. If you know there will be changes shortly, think about deferring documentation of that specific area until the changes are made and the results known. Or, plan to update that changed section of the plan quickly after the document is published.
Make the document easy to read and as intuitive to use as possible
This is probably the section you thought you would be reading on the topic of usable documentation.
A competent technical writer will know about:
- information mapping methods of organization
- using short sentences in paragraphs to convey information
- using bullet lists for complex ideas
- using graphics to support the written word
- using a large point-size serif typeface for readable body copy
- developing a comprehensive index
These elements affect the appearance and readability of the document. If these elements are not included, the document is simply more difficult to use. If a document is difficult to use, generally it will not be consulted.
No competent document is produced on a ninepin dot matrix printer any more. Technology has made it easy and relatively inexpensive to produce graphically-pleasing documents.
But the most graphically-pleasing document will still not be consulted if all effort is poured into design, and none to the other issues previously discussed.
Test the document
Software is beta tested before release.
Products are prototyped and tested with focus groups before marketing. Yet too often documentation is not properly tested before final production.
Usually, the testing phase is dropped as deadlines press. When this happens, the first issue of the documentation becomes the beta version. Errors or ambiguities will surface and will have to be corrected in a later issue. If at all possible, it is better to assemble focus groups and have the documentation thoroughly examined before final production. Using the documentation as an integral part of a mock disaster recovery is an excellent way to point out weaknesses.
Don’t be disappointed if such testing indicates a need for significant changes. It is much better to find this out during focus group or drill testing than during an actual disaster.
Finally: Keep It Simple, Stupid.
Being able to convey complex ideas simply is the acme of the writer’s art. It is for this ability that they are paid.
KISS has a corollary: When in doubt, leave it out.
The tendency in disaster recovery documentation is to include every possible piece of information which may, in some set of circumstances, prove useful.
While the notion is nice, this leads to documentation measured in feet, not inches of paper. Be certain that the information placed in the documentation is placed for a reason, not for a whim. It is always easier to add information to a document later than to take it out.
Treat words as the expensive commodity they are. The size of a document is no indication of its value. The larger the document, the less usable it becomes, since people may become intimidated by it. They feel they cannot find the information they want, therefore they don’t try.
Donald F. Wallbaum is a partner in MillerUpton Wallbaum.Printed In Winter 1994