There are currently two places that define the style of
the TCC's documentation pages. Relative pathnames
tcc/ refer to
Pages under the control of a
PyStyler structure use a
Template in the
root directory of that structure to define the
layout of the web page. Much of the style is
specified using CSS in file
The style of Web pages generated from DocBook is specified by the TCC's local customization layer. See Section 3.1.2, “Local customization of DocBook”.
The formats of Web pages from these two different sources are very similar. They come from the author's ideas on Web style and navigation, learned from Dr. Jon Price, formerly a professor in the Tech TC program.
Chunking is one of the main principles. Assuming that people can get Web pages served to them without too much delay (and it helps if they are small and light on graphics), it's kinder to the reader to present the information in small chunks. The extreme of this tendency is one chunk per paragraph, but that's probably too far. One older rule of thumb is that the principle content of a page should all be visible without scrolling. There are exceptions, but this is a reasonable first approximation.
Here is one way to look at the parts of a Web page:
The head contains the page title, TCC logo, and top-of-page navigational links. See Section 4.2.1, “The web page head”.
The body of the page presents its unique content. See Section 4.2.2, “The web page body”.
The page-end links give the reader places to go after reading the content. See Section 4.2.3, “Page end links”.
The colophon comes last. It tells where the page came from, who to contact about it, and where it lives. See Section 4.2.4, “Web page colophon”.
Right at the very top of the page head is a single line of navigational links. We use text for the links, rather than icons, for two reasons: icons are graphic and slow down page downloads; and icons are not as universally understandable as words, in the author's opinion.
The order of the links is from most important to least important, on the assumption that the reader is from Western cultures that read left-to-right. Here are the links used in both PyStyler and DocBook Web pages, with notes on where they differ:
Next links to the next page in sequence, when there is an obvious sequence. On the last page of a sequence, when it isn't clear where most readers will want to go, this link is grayed out.
Previous links to the previous page in sequence. This isn't the same as the browser's button, because the reader may not have come here from the page previous to it in sequence.
The next link is Index for PyStyler pages, and points to that system's automatically generated index of page titles using a KWIC (Key Word In Context) approach. For DocBook pages, this link is called Contents, and points back to the table of contents for the document.
The idea in either case is to give the reader a place to jump to see the overall structure of which this page is a part.
The next link is to the TCC Help System, in the hope that someone who is really lost will find that system useful.
The next two links appear only on
PyStyler pages: a
link called Publications
that takes them to the TCC publications index, and
a Site map link that takes
them to the
index.cgi application that
allows them to navigate through the outline of the
Finally, there is a link to the NM Tech homepage, so the reader will know what organization hosts this whole structure.
The title tells the reader what this page is about; that's just good basic technical writing.
The TCC logo tells the reader what organization produced this page, and when the reader follows a link to a page without this logo, they know they've reached a page that didn't come from the TCC, and may be less inclined to blame us for any of that page's shortcomings.
These two elements occupy important real estate: the top of the page is where readers look first. Sizing these elements is a balancing act. We want the title and logo to be big enough to read easily, but the more space we take up here, the less is available for content (assuming that we don't want the reader to have to scroll if possible).
Set off from the head by a horizontal rule, the main body presents the actual content of the page.
In order to keep page sizes down and their purposes clear, consider these page rôles:
The purpose of a routing page is to give the reader multiple places to go, along with the information they need to figure out which one applies to them. A common organization of such a page is as a bullet list in which each bullet is a choice. Each choice might consist of just a page title, assuming the page title is all the information they need to choose. Or you could have a bullet like “Sky-diving clubs: you must be affiliated with a club to practice sky-diving”. The first three words link to a page about sky-diving clubs, and the remaining words nudge the reader, telling them why they might need a club affiliation.
In most multi-page Web structures, the starting page is a routing chunk. Its links may lead to more routing chunks as the reader works from general information to the specific information they need.
A leaf page is the end of a path through routing chunks. It presents some bit of useful information, like explaining a concept, defining a term, or describing an occurrence.
A procedure chunk describes a sequence of steps to be followed.
It is rather frustrating to reach the end of a Web page and find no links that take you back off the page. To remedy this, we provide a stereotyped sequence of links that should cover most readers in most situations.
The page-top links are kept on a single line because we want to minimize our use of valuable real estate there. However, once past the page body, space is less critical, so our page-end links give not only a word like “Next” but also the title of the page to which the link is connected. This gives the reader even more information to help them decide whether to follow that link.
Here are the page-end links used in PyStyler and DocBook pages. Most of them work the same as the corresponding page-top links.
Next. If there is no obvious next page, this link will not appear.
See also. Dr. Price dislikes the “Up” links that many page authors use, because they assume that the reader has some idea of the overall structure of the document. He prefers that there be an up link, that takes the reader to the next larger containing section, but he feels it should be called a “See also” link. Assuming that pages have suitably descriptive titles, the reader will be able to tell whether they want to follow that link.
In some cases there may be multiple see-also links. For example, suppose you are writing a document on car engines. At the end of the section on fuel systems, the author can't really predict what the reader wants to read about next—the exhaust system, the electrical system, the cooling system—so provides a set of see-also links for the different choices.
Previous. If there is no previous page, this link will not appear.
Site map (for PyStyler pages only).
Index (for PyStyler pages only).
Help: Goes to the TCC Help System.
NM Tech homepage
Set off by another horizontal rule, the colophon includes:
The name of the page author or authors.
The e-mail address where comments or requests
should be sent. For most pages this is
The last modification timestamp. This is generated automatically by both PyStyler and DocBook.
The URL of the page. This is helpful for browsers whose print function does not show the URL, or for long URLs that don't fit in the heading of printed pages.