Style guide for online hypertext

Structure of hypertext documents

There are two separate structures to keep in mind when writing for the Web. First, there's the structure of your site, the way the documents are connected and can be navigated. It is important that this can be done easily, so that a reader does not get lost when browsing the site. And second, there's the structure of each separate document.

In general, there are a few things to watch out for.

Be search-engine friendly

A very important thing nowadays is to be search-engine friendly. Most of your visitors will find your site through a search engine. There are just too many documents on the Web to find one particular one in any other way. Because of this, you have to make sure that the search engines can index your site properly.

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.

You have the reader's attention

In traditional media, the purpose of an advertisement or flyer is to grab the reader's attention to give him your message. On the Web, you have his attention already. The reader found the URL of your site and came there to find some piece of information. The Web site should not look like a TV advertisement, but instead offer the information that the readers came for.

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."

Don't use imagemaps as the sole means of navigation

Make sure that all documents you want indexed can be reached with normal links (no imagemaps) from the index documents. A search engine cannot use an imagemap to navigate your site. This also makes it possible for people who have image loading disabled to use the site.

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.

Keep the technical details out of sight

If the documents are generated automatically, or indexed by a script periodically, they usually contain special processing information somewhere. Do not put this in the text, but in a comment so your reader doesn't have to see it.

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.