TCC Documentation Guidelines |  |
TCC Documentation Guidelines | |
We distinguish between general webs like the TCC web and the TCC help system, and official TCC publications which live in the TCC publications directory.
A general web is an informal structure designed to help people find information through browsing. Its primary function is to help people chase links until they get what they need.
An official publication is a single, unified document on a single subject. Publications are a better medium when the reader needs to be walked through a sequence of related, interdependent topics, such as in a tutorial, which is intended for people who don't know how to use some system.
Publications are also better for some kinds of reference documents, intended for people who have been through some tutorial or class and just need references to remind them of terms, structures, and such.
Printed versions of publications are handy for situations where the user is away from their computer, or the system is down, or for people who would just rather read from paper instead of a screen.
One way to view a large mixed structure like the TCC Help System is as a pyramid. The user starts at the Help System's homepage and then follows links there to major subject areas, working from large topic areas to more specific topics until they reach the desired information.
However, in practice the upper layers of this pyramid are loosely structured Web pages, with tutorial and reference documents embedded in it.
Currently, a homemade system called PyStyler is used to manage the loose Web pages of both the TCC web and the TCC Help System. Documentation:
Building informational webs with PyStyler (PDF only) is the reference manual.
Summary of PyStyler (PDF only) is a quick-reference guide.
This system is rather dated. It expects page creators to use “tag soup”, that is, HTML (not XHTML). Until such time as something better comes along, though, PyStyler has these virtues:
It enforces a uniform page style, minimizing the amount of work authors have to do to provide navigational links, the TCC logo, and so forth.
It ensures that all internal links within a given structure are valid. That is, if PyStyler runs with no error messages, we can be sure that no links from one Help System page to another Help System page are broken.
The templates that drive PyStyler's Web presentation are quite similar to the TCC's Web customization of DocBook. The next section discusses why the author chose that form of presentation.