The Computer Technology Documentation Project Standards

Documentation Standards

Currently, most documentation is written in HTML, but this may change in the near future to SGML. However, original documents are not required to be in HTML, SGML, or any particular format for submission. We will work with the document's author(s) to perform any required document conversions. Therefore knowledge of HTML, SGML or any other particular format is not required. We are investigating tools to write documentation in SGML and will advise members of these tools as information is available.

Copyrights and Originality

All documentation must be originally written by the author and not copied from other sources. References to other sources is acceptable, but written documentation must either be original or be based on documentation that is legal to use or copy.

Our Documentation guidelines include:

1. Organize the document by function where possible. For each functional area:
   1. Show associated tools used to perform the function.
   2. Show general steps to perform a task. For complicated tasks show the main steps, then break each step into sections with details.
   3. Give specific detailed instructions when appropriate for each step required to perform a task.
2. Structure the subject as logically as possible with consideration for learning and reference.
3. Keep the documentation as brief as possible while conveying a concise meaning. Add no or minimal fluff.
4. Explain the subject in enough detail to give the user a thorough enough understanding to understand the principles of the subject and thereby be able to learn more on their own.
5. Give the user the big picture so they understand how the subject fits into the scheme of things. Eg. What is the need for DNS or DHCP?
6. Explain the use of the technology to the user when applicable.
7. Explain why the technology may be important as a business tool when applicable.
8. Documentation is written from the beginner level up. In some more complicated areas this will not be possible but readers will be able to use previous documents to gain a knowledge base to understand more advanced subjects.
9. Avoid links to outside sources except in references sections of the document. This is because links change rapidly and it is easier to change a few pages than the whole document.
10. Sections to include:
    1. An introduction section at the start of the document which specifies, the name, version, and date of the document. This section should include copyrights, any disclaimers, along with an introduction of the document subject. This section is required.
    2. A credits section at the end of the document with the name, and version of the document along with the author's names, possibly with credits for various sections of the document. This section is required, but may be at the start of the document.
    3. A glossary of terms and definitions as part of an appendix at the end of the document. This section is recommended.
    4. A list of applicable references with web links where applicable. This section is recommended.