Handling revisions

From TechWriter Wiki

Jump to: navigation, search



Although thinking about how to handle revisions when starting a documentation project may sound as appealing to an author as thinking about pensions does to a teenager, a little forward planning at the outset can save a great deal of grief later.

Most technical documentation refers to a specific product (whether hardware, software, or otherwise), and only a complete disaster of a product never gets beyond Version 1. A successful product will be will be built on, enhanced, expanded, and re-released. (Even some disastrous products make it to Version 1.1, even if only to correct the errors in the first version.) It is critical that the documentation must accurately describe the product. Therefore, every time that the product changes, the documentation will (potentially) have to change, too.

Furthermore, it is not unheard of for gaps in the design, or 'undocumented features' (a euphemism for errors) are 'corrected' simply by updating the documentation to include a new warning or caveat, rather than by re-engineering the product. In other cases, functionality or features may be pulled from the product just before the launch, and the documentation has already been sent to the printers.

Finally, although we don't like to admit it, sometimes there are actually errors in the documentation itself. Despite all the checking and double-checking, the occasional tpyo (sic) creeps in.

For all of these reasons, document change is inevitable. And if it is inevitable, you may as well plan for it, so that you are prepared when it happens.

Identifying the documentation level

Each document (and possibly each page of the document) should include the the version number and publication date of the document. Note that this is likely to be different from the version level of the product itself (see Identifying the product level below). In general, Do not attempt to keep the docuemntation level the same as the product level. This is almost impossible to do on an ongoing basis. For example, if changes are needed to the documentation but not to the product, do you hold the changes until the next product version? Or if the product changes but it is not necessary to change the documentation should you issue a new version of the documentation to keep the version numbers synchronized? In both cases, probably not.

Each documentation management system will likely have its own version numbering system. A common system is to use version numbers in the format n.n (for example, 1.0, 1.1, 2.0). The leftmost number is incremented for major revisions, and the rightmost number is used for minor revisions. Note that under this system, a version number of 1.10 is perfectly acceptable for the 10th minor revision to the original document (assuming that the original document is version 1, and not version 0) - you would not jump from version 1.9 to 2.0 for a minor revision - only a major one. This differentiation may be useful when identifying changes.

Identifying the product level

Each document should identify the versions (and/or) models of the product to which it applies. This means that each time a new version of the product is released that the documentation needs to be updated to specify this. However, bear in mind that it will only be necessary to (re)issue the updated documentation with the new version of the product - any documentation already issued with an old version will still continue to be valid.

Identifying changes

  • Revision barring;
  • Change logs.

Tracking distribution

Tracking who has copies, and distribution of updates

May be necessary to have users confirm that they have received the updated documentation and updated their copies (e.g. by inserting the updated pages). Can be done by confirmation letter, or more effectively (if feasible) by asking the recipients to return the old versions.

Handling Last-minute changes

For software, can usually include in the readme.txt file on the disk/CD-ROM.

For other documentation, may need an addenda sheet.

Personal tools