The WDVL Style Guide

Much of the WDVL Style is automatically set by ht and The WDVL Style Sheet. The author therefore has less to be concerned with, and can concentrate on creating better content.

HTML Formatting

I know, this might seem overly constrictive, but I find anything less begins to look ragged. Try to love it.

<ul>
<li>	Start 
	<a href="/Authoring/HTML/Block/">block-level
	tags</a> in column 1, i.e. the leftmost position.
<p>
<li>	Don't indent tags relative to their container,

• Start block-level tags in column 1, i.e. the leftmost position.

• Don't indent tags relative to their container, e.g. keep list item tags at the same level as the enclosing OL or UL. Same for TABLEs and the enclosed row and cell tags.

• All text begins after a tab, so that there appears to be a left-side margin.

• Use tabs, not spaces, for indenting.

• Start anchor tags immediately after the margin, not enclosed by text unless it's very short.

• Line up multiple attributes with the '=' signs all in the same column.

  <Img	src	= "/Icons/Pixels/ffcc66.gif"
  	class	= Button
  	width	= "100%"
  	height	= 2
  	alt	= ""
  	>
  

• Do not let lines extend beyond the 80th column so that the line wraps.

• Break lines preferentially after punctuation marks such as commas, semicolons, and periods (full stops), or before parentheses.

• Do not use more than one consecutive blank line.

Structure

• The Home Page. The function of a home page is usually to introduce and guide readers to the features your site has to offer - it's typically an index page. Top-level documents (home pages) best act as indexes, directing the user to the specific features of your site. So it will be useful to enumerate your offerings under clear headings.
  • Lists help focus the user's attention on a series of items and make digesting many bits of information easier.

  • Headings are preferable to lists, at the upper levels, because the larger, bolder font attracts the eye, and can be easily analysed by programs (e.g. indexers, ToC generators, ...).

• The six levels of headings provide the opportunity to create an information hierarchy. The first heading should reflect the purpose of the document itself, as the title would in a hardcopy document. All headings should be as descriptive as possible, because some Web searchers use this information as a means of indexing document content.
  • Main Header: Usually the same as the title. Use <H1> once only in a document. Internet context specification (what site is this?). Local context specification (Section IIx of this site).

  • Use Consecutively and Sequentially. A heading should not be more than one level below the heading which preceded it. That is, <H3> should not follow <H1>, etc. Always use heading levels in order, with one heading level 1 at the top of the document, and if necessary several level 2 headings, and then if necessary several level 3 headings under each level 2 heading.

• Try to keep a reasonably consistent style between all pages. A uniform page layout will help your users navigate, and give identity to the site. A typical layout is Head, Body, Footer.

• Choose a Meaningful Title. The title is sometimes omitted because it doesn't appear on the displayed document. But the title is what the web will know the document as. Make the title very descriptive, so that when it's saved to someone's hotlist they'll know what it is. Give every page a title that can be understood out of context. Titles should include the organisation as well as the title of the document, so that when they are saved in hotlists, or seen in histories the identification is complete.

• Provide an Introductory Paragraph. Put your statement of purpose onto a web page and view it with Lynx or any graphical browser with image loading turned off. Make this a concise statement of what this page or site is about. People or programs may well want to index it, and the first paragraph is the most likely place for harvesting keywords. To let people or programs categorize the page or site most appropriately, choose your introductory words with care.

• Visual Cues. Guide the reader's eye with structure, rules, fonts, icons, and images. Please don't blink except for emergencies!

  This is a Bordered Table

  Use horizontal rules (<HR>) and table borders to partition the page; but use sparingly. Too many horizontal rules and dividers can make the page look choppy.

Navigation Links

• Don't Say: Click Here ! The user is forced to read the entire sentence to determine what can be found "here," increasing the amount of time needed to access information. Whenever possible put the link on the item itself. Hotspots should be a descriptive and integral part of the text. They should inform users of what they'll be getting, whether it's further information from the same provider, a related document from another provider, a Gopher server, Telnet session, or WAIS search.

  Try to make linking words or phrases part of a meaningful sentence, so that the user has a clear understanding of where they are going once they connect to another page. For example, avoid sentences like, "You can find out more about Baltimore by clicking here. A much better style is: More information is available from Charm Net's Baltimore Page.

• Avoid phrases like Return to... The user may have come directly to this page without having been through the one you want to return them to. Even though you have only made links to it from one place, any other person may want to refer to that particular point, and will so make a link to that particular part of your work from their own.

  Even though your pages may have been created with a particular sequence in mind, it is important to remember that readers may connect to any of the pages in any order. Therefore, your text and vocabulary should stand alone.

• Hyperlinked images. Two common mistakes:
  1. Whitespace before the </a> tag makes a nick.
  2. No whitespace after the Img tag crowds up the text against the image.

• An imagemap can be an attractive and effective way to present your offerings. But provide alternatives requiring less overhead, e.g. a text-only list of the hyperlinks.

• Organize the pages to maximize the user's ease of finding things. The traditional hierarchical structure is a good starting point.

• Provide links; don't forget the text alternates.

• Provide a menubar (remember to offer a text menu too), to enable readers to quickly access the main pages. A few simple but meaningful icons can help people navigate the pages. One at least for the home page is most useful.

• Provide search facilities if the site is complex.

• Home Link. Pages should have a way to go "up" to the home page. This should be a small icon, or a hyperlink, or a menu bar, at the bottom of the page.

Testing

• Validate the HTML. Validated HTML documents will become a key aspect of Web life to ensure document portability. Note that some programs may have difficulty if the HTML is incorrect. There is a validation button at the bottom of most WDVL pages.

• Check the links. It can be very irritating to find several of a site's links don't work.. Check them periodically.

• Test the pages with several browsers - including (at least) one text only, e.g. Lynx. A useful technique is to edit the HTML through a browser, such as lynx. This gives you instant feedback about the appearance of the document on that browser.

• Consider how the pages look on all platforms - Mac, PC and UNIX workstations. Also, how it looks in text-based viewers as well as GUI-based. Add some alternate text to every image, even if it's just the empty string.

Accessibility

• Remember to include descriptions with each image, and try to avoid server-side image maps.
• For tables, you should include a summary of the tables structure and remember to associate table data with relevant headers. This will give non-visual browsers a chance to help orient people as they move from one cell to the next.
• For forms, remember to include labels for form fields.