The latest version of this document is available from <URL:http://www.htmlhelp.com/design/style/>
According to some of the search engines, there are now over thirty million documents on the Web. This means that almost every topic is covered in many locations. If a document is hard to read, or the information therein is hard to find, chances are your reader will go elsewhere instead. That's why it is important to make documents accessible to everyone. This style guide will hopefully help you write easy to read documents.
This style guide requires some knowledge of HTML and the functionality of the Web. The WDG's HTML reference discusses HTML elements mentioned in this guide in more detail.
For a document, the style is also very important. By using a common style, you ensure that a reader can use the site effectively. Some important aspects are indicating the status of the document, using images and icons, and writing in a device-independant way. Also, don't forget to validate your documents!
In general, there are a few things to watch out for.
Normally, search indices will use the first few lines of text from
a document as a short description to display in a search result. If
for some reason you want a different text, use the
<META>
element as follows:
<META NAME="description" CONTENT="Your description here.">
The description cannot contain HTML markup, and should be less than
1024 characters in length.
In the same way, you can add extra keywords:
<META NAME="keywords" CONTENT="Keyword, keyword, keyword.">
These keywords are used next to the ones found in your document. If
you overuse a keyword (some engines use an upper limit of 7
occurrencies) the entire list will be ignored.
That does not mean the site has to be boring and devoid of graphics. On the contrary - just make sure they don't distract from the main purpose of the site. Plug-ins, background music and animations have a purpose, but unless they are essential to the site's message, do not focus the reader's attention to them. And never exclude a reader just because he doesn't have a plug-in for something you offer (don't bother with the mechanics).
Also, if there is more information on some subject, put it on the site, don't just add a 1-800 phone number with the text "Call us for more information."
Imagemaps also often take a long time to load. For this reason, avoid them on the main index pages. An index should load fast so it can be used immediately.
Similarly, if a document uses plug-ins, you can add a link to download the viewer, but don't distract the reader from the actual contents of the document.
It is usually not necessary to include information about the links included in documents. Only add information if the resource is in some unusual format, or is very large. For example, if the site offers a 1.44 megabytes AVI movie, a text like "(AVI, 1.44MB)" after the link could be used to indicate this.
Using the tree model for a Web site, each "leaf" represents a document, and a branch represents a link to that document. The main index then forms the root of the tree, and offers a route to each document. It is not guaranteed that this index will be the only way to reach a document! A reader can always bookmark a file, or locate it with a search engine and then go there directly. Make sure that each document can be used out of context.
To make it easier to follow the tree model, let the directory structure for the documents reflect it. Create directories for each distinc topic, even when there are only one or two documents concerning it. In the future, there might be more information on that topic, and then having the structure in place saves a lot of trouble. Trying to get the rest of the Web to change a reference is a nightmare.
Dividing the contents of your site into logical groups depends on who the expected audience is. For novices, providing a firm structure, perhaps also a "Guided tour", greatly helps to navigate the information. An experienced user might want to skip the introductions and go to the interesting material immediately. This reader has his own expectations about the organization of the information. If the site uses a different structure than they expect, they can become confused and be put off if there is no way to bypass it.
When making a reference, it can be useful to indicate what type of information can be found there. This allows a reader to determine if he should read the linked document. For example, "A step-by-step introduction is in the tutorial" or "The technical details are available in the reference section".
All documents should be available through more than one means. An organized index helps those who want to browse the site, but an alphabetical table of contents, or an alternative index sorted on some different criteria is very helpful. When the information is very technical, or there are many documents available, a local search engine is a useful addition.
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.
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.
Reasons for leaving the document where it is:
Reasons for making a local copy:
The following aspects are the most important:
Instead of the author's home page, there can also be a generic "About" document, containing
copyright notices, disclaimers and the likes. This prevents cluttering up each
document with long signatures. This reduces the information block to
just something like
Copyright © 1996 by Name with the word "Copyright" a link to
that About document.
It is also important to include contact information for comments, suggestions and the likes. This is usually done by adding a "mailto" URL with an e-mail address for this purpose. Always make sure you include the address itself in the text, so people can e-mail you with their favourite mail program. When the document is printed, for example, the link itself no longer works and the URL behind it is no longer visible.
The date of the last update or modification is almost required. If it is at the top of a document, a reader can quickly determine if he has already seen this version and abort the transfer if this is the case. This also explains why it is so important to have a consistent style for all documents: it helps a reader to locate the information he wants.
If the documents are naturally sorted in a specific order, then keeping the flow from one to the next is important. It is not necessary to rewrite the entire document set to help those who jump in half-way, but there should be enough information to prevent them from being completely lost. Some ways to do this are:
In all cases, it is important that images are small. On the Web, an image might be worth a thousand words, but it often costs more than a thousand bytes. Because of the extra delay in loading they introduce, only add images that are essential to the document, and make them as small as possible. And even for essential images, make sure the document still "works" if they are not loaded. Readers on the other end of a slow link will most likely not load any images at all. The ALT text is the most important tool to achieve this.
To make the documents render faster, include the WIDTH and HEIGHT attributes on the IMG element. These attributes indicate the width and height of the image, which a browser can use to draw a box of the appropriate size. It can then continue rendering the rest of the document, and load the image inside the box later. It also makes the calculation of table appearance easier.
If you want to provide large images, then use small thumbnails. They allow a user to get a preview of the image quickly. This is especially important if a document contains a lot of images, as in a gallery. If an image is essential to the text, then inline it, but also add a link to the image itself, so people who do not load images by default can still explicitly load this particular image easily.
Following the notes on document size, keep the size of document and inline images under 60 kilobytes total whenever possible. It is strongly recommended that you put all images in a separate directory, so that all documents can refer to the same images. Since images are stored in the browser's cache, they can be re-loaded from there for every document after the first one.
Make sure the meaning of an icon is obvious, and add effective ALT texts. There are several "standard" icons for navigation. Use these as a basis for your icons to make it easier to identify the meaning of the icon. A magnifying glass, for example, is commonly used to indicate an interface to a local search engine.
For large navigational images, a good technique to reduce loading time when some information on the image changes is to split it up into several small images, each for each part. If the images are loaded, they are put next to each other and should provide a seamless view.
Due to various reasons, the ALT text is rather limited. It cannot be longer than 1024
characters, and it may not contain markup. This sometimes makes it hard to create an
acceptable alternative text for the image. However, the IMG tag itself may be enclosed
in HTML markup, and the ALT text then "inherits" this markup when displayed. Use
the proper HTML tag to mark up the image as if it were text. For example, if the
image serves as the main header for the document, use
<H1><IMG SRC="logo.gif" ALT="The XYZ Company"></H1>
in your document. This either results in the company's logo, or the name displayed
as a level-one header.
Alan Flavell has written an excellent discussion on choosing good ALT texts for images.
There is a difference between using browser-specific or experimental elements in your documents and writing HTML that produces garbage on every browser but the one you have in mind. If you use browser-specific elements, do not try to avoid problems by telling your reader to "Download NetXploder 4 NOW!", but fix your document so it still works if the browser-specific material is ignored.
If the browser-specific elements you use are essential to the document or cannot degrade gracefully on other browsers, then provide an alternative way to get at the information. For example, if you have a complex table in a document, you can make a screenshot of that table available separately.
The block elements can express the meaning of the document most clearly. Use the right one to describe what its contents is about.
As an aside, if a particular element does not "work" the right way in a browser, fix it in the browser, not in the document. Other browsers may handle the element in the desired way, and the "fix" will only break it there. For example, don't skip header levels (from H1 to H3 directly, without H2 in between) just because a particular header looks ugly on your system. Reconfigure the browser instead. If your browser doesn't let you do that, get one that does.
And bear in mind that the site may be "viewed" in unexpected ways, e.g. by indexing robots, character cell browsers, or speaking machines. If the text is marked according to its structure, it will "work" even in situations that you are unfamiliar with: if the text is kludged for one particular browser, there is no way to predict what they will "look" like to others.
Current browsers will support most, if not all, elements from HTML 3.2, but also other, non-standard elements. These are usually experimental and not (or differently) supported in other browsers. Use these with care, and make sure the document still "works" if those elements were omitted.
There are several disadvantages to this technique. First of all, it usually results in a mess in browsers that do not support tables, unless special precautions are taken. Second, calculating the layout of a large table can only be done once the entire table and all images in it are loaded. This can significantly increase the rendering time of the document.
Third, an over-designed layout takes away one of the greatest advantages of HTML: the ability to adjust the layout to the browser's capabilities and the reader's choices. This is particularly a hazard when the table specifies explicit column widths in pixels or is used to force images to be laid out side-by-side. If the browser window is smaller than the table, the reader is forced to scroll horizontally to read it. This is one of the most annoying things to do.
It is recommended that you use the structural elements whenever you can. They allow a browser to present the text with the most appropriate style available on the platform it is running on. If, for example, an italics version of the current font is not available, emphasized text can be displayed in a different color. This is only possible if the browser knows the text is emphasized. When the text is only indicated with the presentation-element I (italics), it can't know that. It could just as well be a citation or book title.
The presentation elements are most useful if the text must be displayed in that way by convention, for example the book title in a list of references.
HTML 3.2 formally specifies the FONT element, which was previously a browser-specific one. Unless you are very careful when using it, it should be avoided. It gives the author a false impression of control over the appearance of the document. If you use it, then bear in mind that many browser situations will not honor the font name, size or color indicated, and will display the text no differently than normal text. Never use it as a substitute for headers or for appropriate logical markups. Start with a document that's properly marked up as to its logical structure, and then, if absolutely necessary, use FONT tags as optional enhancements only.
For a better solution to presentation problems, use style sheets. These are separate documents which can be used to suggest a style for the presentation of an HTML document, or even an entire site.
Especially important for reference documents, but also for indices and home pages, is the printability. People still prefer a hardcopy version of useful texts. If the text is full of explicit references to things that only work on the on-line version, the printed document becomes unusable.
A particularly well-known aspect of this is the "click here" syndrome. That is, hyperlinks with "click here" or just "here" as the anchor text. Not only does it assume that the user is using a mouse, it also draws the attention away from the surrounding text. The reader has to re-read the surrounding text to make sure he is selecting the right "here". A hyperlink anchor should be understandable on its own.
Similarly, things like "Information about X is available by following this link" or "Click here for technical details" are to be avoided. Embed the link in the actual text, in such a way that it is not required to follow the link to understand the text. Instead of the explicit text in the first example, just link the first mention of "X" to the explanatory document on "X". Someone who reads this document off-line will not be able to directly find out more about "X", but the document is still readable.
The possibility to include hyperlinks to almost every resource available on the Internet means that you don't have to include instructions anymore. Before the WWW was started, any document about Internet services had to contain some basic instructions on how to download files, use a mail server or connect to a particular computer. Now, all this can be done with a simple hyperlink, which hides all the technical details from the user.
So, when offering a file in a particular format, do not discuss where to download a program to view or play it, how to save the file to disk or how to decompress it: just add the link and make sure the server sends the right MIME type to identify the file.
Don't assume that since the document renders as you expect in the browser you use, it is valid and will be displayed this way by all browsers. A browser is designed to fix bad HTML, and sometimes it may even be able to completely repair a syntax error so the result is what was intended. However, such fixes are usually dependant on the browser's parser, so a future release (with an updated parser) may repair the invalid HTML differently.
