Next / Previous / Contents / TCC Help System / NM Tech homepage

5. The internal help system

The requirements for an internal help system are very different than those for external documents.

The current recommendation for the bulk of documentation is our MoinMoin Wiki. This system is entirely Web-based, easy to learn and use, and fairly full-featured. To learn this system, see Using TCC's MoinMoin Wiki for internal documentation. This document covers not only functional aspects of MoinMoin, but local style standards.

5.1. When not to use MoinMoin

There is no one perfect system for all needs. Online documentation is handy and easy to create, but some documentations really must be in DocBook for one or more of these reasons:

  • Critical documentation, such as power-down and power-up procedures, and disaster recovery notes, must be available in hard-copy form. Up-to-date copies must be maintained in the ring binder on the table in the back right corner of the server room.

    It does you no good if you lose the Wiki server and the instructions for putting up the Wiki server are located only there! Even more critically, information on server configuration must be available when the servers are down.

  • If a document is critical, but is also sensitive, it should be in DocBook so that hard-copy is available. However, normally DocBook produces Web pages, but we obviously don't want them up on the Web! In this case, use DocBook, but apply group tcc protection to its directory, so that the only form available is the PDF, and that is available only to TCC staffers.

  • As nice as MoinMoin is for quickly creating decent documentation, it gets unwieldy for many documents. See Section 5.2, “Limitations and problems of MoinMoin”. If you are doing a sizeable document and these things start to bother you, you will find that DocBook has none of these problems.