HTML Guidelines

This set of "guidelines" is being written for the novice or casual user to follow when composing HTML for the World Wide Web. This is not a reference guide to HTML. The intent of these guidelines is to help you write HTML that works with and looks good on a variety of different browsers and to produce HTML pages that are easily found, read, and maintained.

Table of Contents

Basics

Formatting

Graphics

Content Issues

Using Links

Use of URLs

Device Independence

Maintenance Issues

Links to Information About Style and HTML

Basics

Sign your work. It is important to indicate who is responsible for the content, together with copyright information, if there is any. Include author(s), status of the work (in progress, Internet draft, final draft) and date. In some cases you may want to reference both the author of the original document and the person who is responsible for the electronic version.

Date the page. There are several preferred ways to format the date. Choose one and be consistent. While the US uses mo/da/yr, the rest of the world uses da/mo/yr. The form "year mon day" (for example, 1994 Dec 07) is unambiguous and allows for the turn of the century. This format could be used to automatically check for out-of-date information.

Formatting

Don't use tricky HTML to do page formatting. There are clever ways to do indentation, spacing, centering, etc. that will work on a particular browser but won't have the desired effect on all browsers. Don't embed extra spaces or blank linesas they may not be rendered the same way on all browsers.

Use complete phone numbers (with area code).

Make your document printable or provide a link to a "printable" document. You may also provide a link to a version of the document without graphics.

Graphics

Avoid the overuse of graphics. They can't be seen on all browsers and they slow down load time on most browsers. Keep the size and number of inline graphics (graphics that are displayed as part of the page) down. When using graphics, use the alt="Picture of Whatever" option to define an alternative for text-only browsers to display instead.

Check the copyright status of any graphics you download. There are millions of images on the Internet, and Web browsers allow you to acquire and reuse any of them -- but you could be violating copyright laws in doing so. If you aren't sure whether the original owner of an image intended it to be used by others, send them e-mail and ask.

Content Issues

Know your audience and keep it in mind when composing HTML pages. Is a large part of your audience at schools or colleges that use text-only browsers and telnet connections? If so, then your graphics may be gratuitous. Are you trying to reach a home audience of America Online and Microsoft Network subscribers? Then some of your Netscape formatting may not have the intended impact. (See "Device Independence.")

Order of items within lists. Use chronological order for periodicals, with the most recent as the first. Use alphabetic order for others, unless there is a reason to do something different.

Keep the content level high. Make pages that contain more than just links to other things. Although some pages may be set up for just that purpose.

Put keywords in comments. For search engines (like lycos) include comment lines at the beginning of the html file that contain keywords describing the document. (Comments fall between the special <!-- and --> markup elements. There must be a space after the initial <!-- and preceding the final -->)

Using Links

Provide a standard menu of links at the bottom of the page for easy navigation, especially in material that spans several Web pages. Create an HTML table of contents (of links) for organizing longer documents.

Use meaningful text inside of tags. It improves the readability of the document. Avoid phrases such as "click here"--not all browsers use the mouse to click on links. Avoid using "here" as an anchor. It's better to use one or two words describing the content as the anchor.

Link to context. If part of document may be cited from outside, permit the user to know the relevance to the whole document. For example, explain an acronym the first time it's used after a link even though it may have been defined earlier. In some cases, you may want to link acronyms or technical terms to definitions on a separate glossary page.

Use of URLs

Use relative URLs with caution. A relative URL does not specify the complete "address" for the page. For example, if you had a page http://fog.ccsf.cc.ca.us/~jdoe/my.html with links from it to another page in the same directory, you could refer to it as href="another_page.html." Relative URLs are shorter and make documents easier to move around, as long as the directory is moved as a whole. However, relative addressing may not work the same way under all browsers.

For the College's personal page web server, fog, a link to an inline graphic or other file name as a relative URL may not work unless the visitor comes to your page by typing the URL as "http://fog.ccsf.cc.ca.us/~jsmith/" -- including the slash at the end. A full, explicit URL doesn't put this extra burden on the user.

Use fully qualified domain names when specifing URLs. Within a particular domain, a reference to http://fog/~jsmith/ may work. However, machines outside this domain will not be able to find it. Use the fully qualified domain name http://fog.ccsf.cc.ca.us/~jsmith/, and any host can find it from anywhere on the Internet.

Device Independence

Create browser, computer, and bandwidth independent pages. Make your work available to all by writing pages that are both browser and bandwidth independent. Different browsers display pages differently. Test a page with a variety of browsers to check out how it will look in each. Check appearance of page on minimal browser, such as Lynx.

Avoid overly long documents to minimize transfer delays and ease scrolling difficulties. Long documents, especially graphics, should have the size included next to the link so users will know what they're in for before following the link.

Maintenance Issues

Only publish what you have time to maintain. Always consider that information ages and will only be useful for a limited time unless updated.

Maintain your links by keeping them current. There are some tools available to help maintain the validity of your links.

Use machine independent server names when possible. For example, on cloud' server, use www.ccsf.cc.ca.us instead of cloud.ccsf.cc.ca.us. That way if the server itself is changed your links will still work.

Include a comment statement about all the documents that are linked from the document you are working on. In other words, all the documents it depends on. (Comments fall between the special <!-- and --> markup elements. There must be a space after the initial <!-- and preceding the final -->.)

Create an organized directory/file structure. Use meaningful file names. Have a top level directory for common elements such as images.

Links to Information About Style and HTML

Web Page Authoring Basics

Web Page Advanced Design

Yale C/AIM Web Style Guide (Yale Center for Advanced Instructional Media)

The HTML Style Guide from CERN

HEASARC HTML Style Guide

Composing Good HTML

Writing HTML Guide from MIT

Beginner's Guide to HTML from NCSA