Style guide for online hypertext

The structure of a single document

As said in the introduction, an on-line document can correspond to a whole book, or just a footnote. Usually the document will be something in between, which means that there can be more than one HTML document for one piece of information. The most important thing here is that one document should contain one well-defined concept. Just splitting a file to reduce its size, or join many small files into one is not generally a good idea.

If the information is available in separate documents, the reader has to load each subdocument to read it. On a slow network connection (or busy server) this might take longer than the reader is willing to wait.

However, presenting everything in one large document also has its disadvantages. If it does not fit in one "screen" (whatever is displayed at once in a browser window) then the reader has to scroll through the document. If his interest hasn't been grabbed within the first couple of screens, he will likely go elsewhere. To prevent this, don't split up the document into arbitrary pieces, but add an overview and perhaps a table of contents at the top.

A one-document, or archived/compressed version of all the information on a particular topic is often useful. A reader can then download it and read (or print) it offline.

It's hard to give even a rough size for the size of a document, since there is no way to predict how much space a document will occupy on a reader's screen. One of the few aspects you can control is the loading time. A typical speed for loading a document is about 1 kilobyte per second. Many people use slow modems, and even when the physical connection is faster, the network can be very slow.

For introductory pages, tables of contents and the likes, keep the total size (text and images) under 60 kilobytes in all cases. A size of 30 kilobytes is a recommended upper limit, since then a document takes only 30 seconds to download and render completely. Any longer and your reader may go elsewhere.
Informational documents should be split up in separate documents, as discussed above. There are situations where this is impractical - if each aspect is contained in one or two paragraphs of text, splitting it up is not necessary. A reasonable upper limit for such documents is 60 to 100 kilobytes. To make things easier for readers, the document could also be made available in a compressed archive, or in a one-part file.

On a related note, make sure that any navigational images in documents are less than 450 pixels wide. Most browser windows are about this size, and if your image is wider, the reader has to scroll horizontally to view the rest. For preformatted text, use a maximum of 75 characters for the same reason. Scrolling horizontally to read a document that is slightly wider than what you are used to gets tiresome really quickly.

Having a table of contents does not mean you can't directly link to documents available from it. Include links between related documents (e.g. "Next", "Previous", "More") so that readers aren't forced to navigate to the table of contents (this is known as the "staircase syndrome") every time.