A doc (documentation) plan, often called a project plan, is a written explanation detailing all components of a technical writing process. To understand how best to approach preparing this plan, it's necessary to understand some specifics about any technical writing project.

The main purpose of a technical document is to convey information. The document should place as few hindrances as possible between the mind of the writer and the mind of the reader. A secondary function is to stimulate and entertain. There are people who can inform and entertain at the same time. Like most people, however, you will have to make a choice between the two. And this means you need to inform rather than to entertain. Of course, if you were writing a novel the priorities would be reversed; but in document writing it is the information that is paramount.

A good document needs careful planning. As part of the planning stage you should try to answer the following two questions:

• What is the document about?

• What are you trying to say?

You need to arrange things so that the key facts and conclusions are accessible. Not everyone will read the entire document, so make sure that your message gets across even if a person only skims the document.

So, just who is it you are writing for? It is impossible to write a technical document that will be equally easy for everybody to read: the level of explanation you need for an expert audience is totally different from that needed for readers who are unfamiliar with the subject. It is essential that you identify the potential readers before you start working. If you are writing for computer scientists you don't need to explain, for example, what a modem is, nor the World Wide Web, but you may need to explain what “baseband” is, and what “ppi” stands for. If you are writing for people who have no knowledge whatsoever about your topic, you'll have to go into greater detail; you may need to define terms within the text, which also provide the context, or provide an all-inclusive glossary at the end of your text. Regardless of your audience, keep the level of knowledge in mind and try not to wander too far from that level.

Once you know the exact nature of the job ahead and have an understanding of when your written documentation is to be completed, you're ready to begin preparing your doc plan. One way to do this is to begin with a “Preliminary Project Plan” to help organize information as it's gathered and considered. In order to complete such a project, you'll need to be able to determine the following:

• Project description: Think of this as the “mission statement” for the project, a one- or two-sentence description of what your document should accomplish.

• Title: At this point, you can use a working title; as long as you have something that serves to designate the particular project, it should suffice.

• Project incidentals: Notes about the purpose, scope, and limitations of the document.

• Audience: This is probably the most important aspect at this point. To know how to proceed, you need to know who will be reading what you write. You'll need to know your audience's education level and technological expertise — as it applies to the project.

• The why and the what: The reasons why the documentation will be used by the intended audience, and for what purpose.

• Proposed table of contents: Often referred to as a “fluid document,” this draft table of contents is the map that details the direction your document should take. It will be modified as you go along, but it helps to plot out your objective and to ensure that you're marshalling your information in the best way possible.

• Deliverables: Unless you're writing a technical document on assignment from a publisher, you'll often handle other details beyond just writing. Deliverables can include printed copies (how many?) and details like whether disk copies are to be supplied, disk and file formats (including software versions), and where and when they are to be delivered.

• People and other resources: Who and what resources will be available to help you? How many work-hours will be required? At what cost?

• Change control: This would cover procedures in place for passing information about program changes to the documenter during the development of a software manual, for example.

• Milestones: A schedule showing appropriate milestones, such as when the documentation plan was approved; the preparation, review, and approval of each draft; the index completion; the usability testing; the camera-ready artwork preparation; and the printing, binding, and distribution.

• Source material: What written information is already available?

• Standards and specifications: Is the documentation to be written to a particular standard or specification?

• Technical edit: Who will check the technical accuracy of the manual? Whose responsibility is it to hire (and pay) the technical editor(s)?

• Editorial control: Who has editorial control?

• Budget: An estimate of what it will cost — in time and out-of-pocket expense — to complete the project.

• Copyright: Who will own the copyright and any other proprietary rights? Usually, the author of a commissioned document is the first owner unless a specific work-for-hire or other agreement states otherwise. (See Chapter 10 for more information.)

• Translation responsibility: Provisions for the translation into other languages, if applicable.

Getting answers to these questions allows you to develop a suitable project plan. One scenario is that once you have your preliminary project plan, you'd then discuss it with the project manager. After any amendments that might arise from those discussions have been added, it should be signed off on or otherwise formally agreed to by both parties.