Documentation lives and changes. Just as Zope changes so does its documentation. Maintenance allows documentation to stay accurate.

Dealing with Zope Changes

When Zope changes, all the documentation affected by the change must be updated. These changes are driven by developers. See Documenting Your Zope Changes for a description of how a developer documents their changes to Zope. As a manager it is your job to help the developer document their changes. You may need to edit their contributions. You will also periodically verify that developers have been doing their job (see Verifying Documentation below).

Dealing with Reader and Reviewer Feedback

When users read documentation and have trouble with it, they need to be able to offer feedback. Someone must then respond to the feedback and make any needed changes to the documentation. All documentation artifacts include email and web-based feedback. This feedback is collected in the project's tracker.

Similarly anyone can visit a documentation project page and review the materials there. They may wish to offer comments on the project's goals, scope, and audience. They may also wish to comment on drafts of the documentation. This feedback is collected in the project's tracker.

It is your job as manager to respond to these comments, fixing problems, and perhaps initiating enhancements by locating authors and editors to perform the enhancements.

Enhancing Documentation

Sometimes an author decides to enhance a piece of documentation by rewriting or adding information. Often this author may not be the original author of the documentation. For example, a How-To author may wish to have their insight incorporated into the Zope Book. The author's enhancements need to be evaluated and folded into the documentation in a coherent way. Other enhancements may be prompted by reader feedback or by developers who want to improve the documentation. In any case it is your job as manager to make sure that enhancements get edited by an editor and folded into the documentation when ready.

Verifying Documentation

In addition to on going maintenance, all official docs will probably need to be audited periodically to ensure that nothing has slipped through the cracks.

A good time to do this would be when a new release of Zope is made. At this time, all official docs will be briefly audited. If they seem up to date with the new version of Zope, they will be marked as covering the new version of Zope and will be re-published. This system would have the advantage that readers could easily tell if docs have been checked with the new version of Zope.