Section 8.9. Checklist

8.9. Checklist

Here are some questions you should feel comfortable answering about your current documentation system. For the first set of questions, imagine that you've found a serious technical error in the content of a document about your own product:

• How do you tell someone that this error exists? Do you file a bug? Send her email? Annotate a printout?

• Can you easily find out who is responsible for the particular document?

• Where do you find the version number of each document?

• How do you know when to check for a corrected version?

• Where would you go to find the corrected version?

Some more general questions to ask yourself about your documentation environment are:

• Can you view and print the released documents from all the environments you work in?

• When do updates to the documentation appear?

• How is feedback from reviewers incorporated into your documentation? What sort of information do you imagine is lost or garbled during this process?

• When you want to resolve conflicting input from different reviewers, is there a record of who approved each change to the document? This is often available either as part of the document itself or by using an SCM tool.

• What file formats do you deliver to customers, and why?

• How long does it take to convert all the source files for your documentation to the formats that are delivered to customers?

• How much of the time generating the documentation is spent doing things manually that have to be repeated every time the documentation is generated?

• On how many different machines can you create the released versions of the documentation?