An HTML Style Guide

by Robert Lentz (ralentz@ralentz.com)

Introductory Remarks

One of the most important concepts in writing HTML documents is to allow your document to control the layout, rather than trying to impose a layout on the document. You should have an idea of how you want to present the document, in fact, this is important to getting started, but as you write your document, you will find that you have left your starting point and are venturing down a path towards some other destination. After each document you will find that you know more HTML and undestand better how to present your documents. You will also find yourself wanting to go back and enhance your older documents.

The entire process has been compared with sculpting (having to release the statue from the stone). (If you are comfortable with scripting languages, you should seriously consider learning Perl to assist you with your document maintenance.)

In all cases you should try to keep "top level" documents as small as possible so people are not rudely surprised by having to wait for a large document or lots of images. In all cases you should warn the user if following a link will possibly result in a long wait due to image size or complexity.

Proper Document Structure

<html> </html>: These two tags should be the first and last lines in your document. They explicitly tell a client that this document should be interpreted as containing HTML commands.
<head> </head>: This set of tags delineates the top section, or "head", of your document. Within this section you would specify the <title>, <base>, and any <link> tags.
<body> </body>: This set of tags marks off the rest of your document.

While most browsers currently do not require these tags, you should include them to assure proper future funtionality.

Document "Ownership"

It is typical to "sign" each document, including the last modified date, at the bottom. This can be your name or your initials, and may even include an email address, otherwise the signature is usually a link to a document, usually your "hyplan", which includes information on how to contact you.

A more formal method has been adopted which clients can use to allow a reader to send comments or problem reports to the author. This involves a "link" tag, within the "head" section of your document, such as: <link rev="made" href="mailto:ralentz@ralentz.com">, but you of course would use your own email address.

Both methods should probably be used.

Hypertext Labels

Hypertext links should be an unobtrusive addition to your document. An anchor should be made from some already existing text, and not tacked on in a "click here" reference.

Forms

The forms interface is one of the most powerful new capabilities of Web clients. However, since it is new, not all clients support it yet, and thus not everyone will have a forms-capable client for a while. Therefore, for any application to which you provide a forms based interface, you should also provide a non-forms based interface as much as possible.

Inlined-images

First, a slight digression for some background on who uses the Web, which is relevant to inlined-image and large documents: Your readership will likely include people from all over the world, using the networks at all times of day, with a wide variety of network connections including slow dialup lines, and using a variety of clients including text-based clients.

While a great portion of the excitement over the World Wide Web and Mosaic involves the multimedia capabilities, these capabilities must be used only when appropriate, or at least sparingly; otherwise your reader faces the prospect of waiting for upwards of half a minute for you document to load. Most of us have by now run into documents which take a seemingly long time to load and can thus sympathize.

Not only will large inlined images provide sluggish response, but lots of images, even small "thumbnail" images, will cause a sluggish response in the loading of your document. (The author suggests no more than 20K and five images per page. More information on readership impact, based on the author's experience, is available.)

Large numbers of inlined-images can also provide a display problem. Most color displays will only be able to deal with 256 colors simultaneously. Large numbers of images with differing color maps will soon fill this, impacting negatively on each other and whatever else the reader's monitor might be displaying. Using grayscale images is one way to minimize this problem.

A similar display problem occurs because not everyone uses a color monitor, many people will be viewing from monochrome displays. This should be kept in mind when designing, or deciding to include, your images. You should probably test out the look for yourself by changing your monitor's setting.

If an image is central to your communication, especially as a link, you should also include an "alt" attribute in your "img" tag.

If you must burden a document with large (numbers of) images, first consider making them external images, with a description within the document as a link to them. Another approach would be to just include a smaller, thumbnail, version within the document as a preview and a link to the real version. In all cases you should warn the user if following a link will possibly result in a long wait.

Navigational Aids

Since your readers will have the ability to jump right into any document without necessarily following a predefined path, you probably want to include links to key parts of your document structure within each of your documents.

Since most clients have a cache for inlined-images, you could probably use a consistent set of navigational icons throughout your hierarchy, though the cache would be negatively impacted upon by any other inlined-images you use. Once we have a campus image server, it would be advantageous to standardize on a set of navigational icons. (For a variety of reasons the author is partial to textual buttons, constructed by <enclosing a link> with angled brackets.)

TOCs/Overviews

To aid people in finding information/exploring without wasting a lot of time, you probably want to maintain a "Table of Contents", or "Overview" document for your hierarchy which people can reference and then jump straight to the parts that interest them.

You probably also want to provide a "What's New?" section so people can easily see what has changed or been added. (The author is partial to a small section at the top page of a document tree as it avoids the trouble of retrieving two different documents, or storing two different links.)

Outlines for Large Documents

With HTML's ability to link documents together, and the sometimes slow network links, large self-contained documents are generally frowned upon. Unfortunately, because it is not currently possible to print or save a "group" of documents, you must go through each one-by-one to print or save them. Thus, breaking up a large document into a document "tree" is not a very good solution either.

A compromise is to provide an "outline" of the document as a separate document which people would first browse. The sections of this "outline" would refer to "named anchors" within the target document; this way readers do not have to waste time downloading the main document. You would probably also want to provide a copy of the outline at the top of the document for people to refer to once they have accessed the main document. This copy of the outline would use only the named (href="#name") portion of the corresponding URL to avoid reloading the main document. Then within the document, at the end of each section, you could provide a link back up to the in-document outline.

Indexing

With the tremendous volume of information available through the computer networks, information discovery is a large problem. Discussion on WWW indexing systems has not yet completely settled on a specific method, but there is a leading contender which it is probably safe to start working with.

Document Caching and Expiration

Several methods of caching documents are in the works, though none are yet mature enough for general use; we will continue to keep an eye on these developments.

In preparation for this eventuality, if you are planning on publishing dynamic data, you can include expiration information within your document. This is done through the <meta name="Expires" value="Tue, 04 Dec 1993 21:29:02 GMT"> tag and attributes in the "head" section of your document.

Tags It Would Be "Really Nice" to Include

<base href="url">: This "head" tag, and attribute, explicitly tell the client how to refer to your document and their use is recommended. A problem can exist when using these during the "edit-reload" cycle on a "local" machine, thus they would be the last thing you would add before moving your documents to a server.
<a name="name">: This "named anchor" tag can help you, and others, more easily navigate documents. You would especially want to consider using these generously within your document if you are preparing a document that has sections to which others might wish to link.

4/2/94 - Robert Lentz (ralentz@ralentz.com)

< To HTML Thoughts...> < To Robert's Home Page...> < To Astronomy Home Page...>