How to write and maintain the JANUS documentation

General Guidelines

• Make sure you read the introduction to the documentation and got a feeling of the structure. Always keep in mind that links that show the structure of the document (next section, subsection) should be clearly seperated from links that jump to random places in the document.
• Remember your Priorities: Content > Structure > Form
  make it a point to always rather keep the information in your pages up to date and readable than adding fancy pictures or reformating the whole thing.
• We plan to use RCS to lock versions of the documentation while changing them. Therefore use unique file names (also in subdirectories always make sure that filenames will still be unique in a flat structure).
• Minimum Requirements for a page:
  • All pages should have a pointer back to the next higher level in the documentation.
  • Pages may should a pointer to the next subsection on the same level in the same section (if any) where appropriate.
  • Each page should have a global header in H1 size.
  • Subheaders should not be larger than H2.
  • All pages should have a mainainer.
• Maximum Requirements for a page:

Module Documentation

The documentation for a JANUS module consists of several files, that are kept together in one subdirectory for the module. Each module can contain several objects on the tcl level. If you stick to the convention to find two letters for your module and start all documentation files with these, it's easier to avoid doublicate filenames in the RCS directory.

As a general rule, there are the following files:

• xx_main.html:
  Introduction to the module xx. What does it do and contain. what is the role of xx in JANUS. Pointers to file formats, tcl stuff, c-code infos, tcl examples.
• xx_file.html:
  File formats for this module including small examples.
• xx_tcl.html:
  Tcl methods, configurations
• xx_c.html (optional):
  Source code hints for c-hackers
• xx_tclscripts.html (optional):
  Pointers to and explanations of example tcl-scripts. If those scripts are very short they can also be inline.