TCC Documentation Guidelines |  |
TCC Documentation Guidelines | |
The requirements for an internal help system are very different than those for external documents.
Security is essential. Internal documentation must be password-protected so only current TCC employees can even see it.
Style is somewhat less important. Unlike external documents, we don't care so much about a consistent look and style. However, style always matters when it comes to clear presentation of the material.
Because some people find it tedious to write documentation, we need to make the task as easy as we can.
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.
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.