Document Formatting Conventions

A few things to keep in mind when editting our QA docs and *.html pages for track details pages.

1. Limit lines of code or text to 80 characters. It fits in a terminal window without wrapping in the middle of a word. If you use an HTML editor, please add a line break at the end of each line.

2. Nest your tags with two spaces (NO TABS!). Tabs use up too much screen and the contents get squeezed to the right too far. Open- and close-tag pairs hould usually be above one another, especially <TR> and <TD> in tables. <P> and <LI> might not.

Here is a sample row in a table with a double-nested set of list items:

<TR>
  <TD>
    <UL>
      <LI>The text that would go here in this set of bulletted contents
        should be aligned so that all the text is plainly readable and
        the text for one cell of the table is aligned with other text
        at the same level in the HTML.
      </LI>
    </UL>
  </TD>
  <TD>This is the second cell of the row.  It has no bullets.
  </TD>
</TR>

If you run across docs with formatting that deviates from the standard, please clean it up locally, at least, before editting. There is no need to clean up the entire doc, but make the section you are working on conform. You should do two commits into CVS. The first should clean up the formatting of the existing table cell or paragraph to bring it into compliance. You can commit that as just formatting to make pair review easier. Then commit the actual change in a second commit so the reviewer can see the diff in content and not have to slog through formatting issues.

3. Filenames should be short and use interCapping: lowercase first character followed by uppercase for words that follow. Do not use underscores. E.g.: qaDocFiles.html not qa_doc_files.html or qa_document_files. That said, abbreviations should be obvious and avoid removing only one of two characters. E.g., "tbls" is not much of an improvement over "tables" and is harder to remember.