Example Style Guide

The following document is a style guide for producing content for the [client] Web site. This document outlines basic principles for adding content to the site, defines the basic style sheet classes available to content managers and how they should be used, and defines principles, guidelines, and best practices for content.

1.0 Coding Standards

The [client] site is designed to the XHTML 1.0 Transitional and CSS specification as designed by the W3C (World Wide Web Consortium). The most important standard for content managers is the XHTML 1.0 specification. All code added to the site must validate as XHTML 1.0. The following sections will explain how to make your code validate and how to check your validation.

1.1 Why are Standards Important?

Much non-standard HTML looks just fine in your browser, so why is maintaining standards so important? There are actually several compelling reasons.

1. Standards mean that the site will be up-to-date now and will be easier to keep up-to-date in the future. Writing code with standards means all of the code on the entire site matches a single specification that will be supported by future browsers. Just because your pages look good now on your browser does not mean they’ll look good in future browsers unless they’re compliant with modern standards.

2. Standards make the site faster. Particularly using CSS, the amount of actual code being sent to the visitor is significantly reduced, making visitors happier with load time and system administrators happier with server load.

3. Standards make the site more accessible for users with disabilities. Simpler, cleaner code is easier for screen readers to interpret. Scalable font sizes make text easier to read for people with reduced sight. Descriptive ALT text helps people who are unable to see photos or read graphical text.

4. Standards make the site more versatile to work on non-traditional browsers. More people are using handheld devices, cell phones, and other technologies to browse the web. These devices have different requirements and standards code is much more scalable for such applications.

1.2 Writing XHTML Valid Code

There are a number of key rules to keep in mind when coding to be XHTML compliant. Remember these and you’ll have no problem making your code work.

• Use Lower Case in Your Tags

  Always use lowercase text in your HTML tags. Even in attributes always use lowercase.

  Wrong:	<IMG SRC="landscape.gif" ALT="Rural Landscape" WIDTH="40" HEIGHT="10" />
  Right:	<img src="landscape.gif" alt="Rural Landscape" width="40" height="10" />

• Close all of Your Tags

  One of the keys to XHTML is that all tags have an opening and a closing. This was common for most tags in HTML, but in XHTML every single tag needs to be closed. For instance, make sure all of your <p> tags are followed by a </p> tag at the end of the paragraph and all of your <li> tags are followed by a </li> at the end of the list item.

  This makes sense for most tags where there is a logical closing tag, but there are some tags where this seems a little strange at first. Images, horizontal rules, and line breaks, all are single tags in HTML so there is no proper closing tag for them. In XHTML you need to put a closing slash inside each of these tags to essentially open and close the tag all in one. Examples:

  HTML	XHTML
  <br>	<br />
  <hr>	<hr />
  <img src="image/graphic.gif" alt="">	<img src="image/graphic.gif" alt="" />

• Nest Your Tags Logically

  XHTML is very strict about how you nest your tags (placing tags inside other tags). Some tags can not be nested inside each other. For instance, you can not place a bullet list <ul> inside a paragraph. When you validate your code, the validator will indicate if you have nested tags inappropriately. Also make sure you close your tags in the same order you opened them. For instance:

  Bad Example:	<strong><em>Example Text</strong></em>
  Good Example:	<strong><em>Example Text</em></strong>

• Use Quotes for All Attributes

  All of your attributes for tags must be surrounded by quotes. For most tags this means just making sure you have quotes around your numbers and other attributes.

  <img src="images/graphic.gif" alt="Graphic" width="200" height="40" />

  For some other attributes this gets a little more complicated. Some attributes that did not require descriptive elements in HTML require them in XHTML. The ‘nowrap’ attribute for <td nowrap> tags or the ‘selected’ attribute for <option selected> for example. Now, these cannot stand alone in XHTML. To make these compliant, you need to add a description of the attribute. For example: <td nowrap="nowrap">

• Add All Required Attributes

  Some tags have required attributes in XHTML. You just need to make sure you have all of the required attributes set to validate your code. All of your images require alt text for instance. The validation tool will tell you when you’re missing attributes.

• Use Only Accepted Characters

  The XHTML standard limits the use of a fixed character set. Some characters, such as curly quotes, will make your code invalid. If you need to use a special character, use its HTML character entity. A list of acceptable entities can be found at http://www.w3schools.com/html/html_entitiesref.asp and ASCII entities can be found at http://www.w3schools.com/html/html_asciiref.asp

• Do Not Use Deprecated Tags

  Some tags that used to be used have been deprecated and should not be used. The most common example is the <font> tag. Font tags should be replaced with their appropriate style sheet alternatives set with classes. As well, bold tags should be defined with <strong> tags and italics should be defined with <em> tags. Center tags, <center>, should be replaced with <div align="center">.

1.3 Validating Your Code

The easiest way to ensure you’re writing XHTML 1.0 valid code, you can use the W3C tools to validate your code. Every page should be checked before it is put on the live site.

To validate your code, use the Favelet for “Validate This Page” available at http://validator.w3.org/favelets.html. When you add this as a bookmark or link in your browser you can quickly validate the page as you work on it.

2.0 Using Style Sheets

The [client] site has a well-defined style sheet that can be used in all new content being added. As much as possible, content managers should try to keep to the standards set out in this style sheet to maintain conformity throughout the site. Also, as much as possible, basic tags should be employed where complex formatting can be avoided. For instance, definition lists and unordered lists should be used wherever appropriate and table formatting of content should be avoided wherever possible.

2.1 Header Tags

As much as possible, titles on the site should be defined with the appropriate header tag. Graphical titles should be avoided wherever possible. All six header tags are defined in the style sheet and should be used appropriately. The <h1> tag should most often be used as the page title at the top of the page.

2.2 Special Text-Formatting Classes

As much as possible, normal text should be used throughout the site. However, in certain instances text formatting is required. The following are some simple ways to format text.

<div class="subtext">	Text inside an element with a class of subtext will appear smaller.
<ul class="spaced">	All list items (bullet points) within the list will have a line space between them. This works for <ol> and <ul> lists.
<p class="first">	Removes the automatic margin on the top of a paragraph. Usually used for the first paragraph following a header.

3.0 Content Guidelines

Aside from the strict rules governing compliance with standards, there are a number of best practices which should be followed for all content added to the site. Some of the following guidelines are basic principles to work by and some are specific guidelines that give specific directions for content management.

3.1 General Principles to Follow

• Site Visitors are Your Most Important Priority

  This may seem obvious to some, but it’s vitally important to keep in mind that every content decision must center on the site’s visitors. For the [client] public Web site, this means all content must be focused on a general audience that includes a wide variety of people with different needs, different computer experience, and different experience with your department.

  All of the decisions you make—naming sections, layout, navigation, content, graphics—should be centered on the site’s visitors. This means making the type legible, using clearly understood titles, making your content accessible, and being consistent with the practices on the rest of the web as well as within the [client] site.

  Try not to focus your content on any particular group too closely as many other people you might not expect will likely visit your pages as well. For example, even if your section is primarily written for “clients,” other people are likely to browse your content as well. Remember that people outside of your group may not know your acronyms, proprietary phrases, and other custom material. Also keep in mind that your section of the [client] site is not the only part of the overall site that your audience will be browsing. The site must me consistent. Because visitors expect consistency, be consistent across the entire site to ease their navigation and so all of the content appears cohesive and part of one system.

• Consistency is Vital

  Consistency is very important for the entire [client] Web site. There are two key reasons consistency must be maintained:

  1. Users become familiar with consistent design and can more easily navigate a site when the navigational elements remain consistent throughout the site.

  2. Consistency maintains a common feel, which indicates a cohesiveness of purpose, of trust, and of common source for all content.

  Being different for the sake of standing out or being ‘creative’ is not reason enough to break from the consistent design of the rest of the site. Remember that each section of the site is only a part of the whole. The visitor understands the [client] site from the perspective of the whole site, not any one particular section.

• Creativity has its Place

  There is certainly room for creativity within the [client] Web site. In particular, your content itself is the most important venue for creativity. Providing user-focused content that effectively addresses what visitors need to know is your key task. Graphical elements should be used to support good content—do not let graphics overwhelm your content.

• Keep it Simple

  Keeping your content and layout simple serves several purposes:

  1. On the Web, simple usually translates to fast. In your office, the site may load almost instantly, but people using modems will experience a delay before their page is displayed. Use strategic graphics to enhance the meaning of your content, but always remember that the larger your graphic files are the slower your page will load. Visitors are more interested in getting your content quickly than in waiting to view unnecessary pictures.

  2. A simple layout is easier to understand for visitors. If you keep your navigation structure simple and organize your content carefully, your pages will be easier and quicker to navigate for your site’s visitors. Extraneous graphics and formatting will only get in the way of your visitors.

  3. Simple content means visitors will understand what they’re reading and will be able to more easily find what they are looking for. Keep your content in short descriptive paragraphs to help your visitors browse efficiently.

  4. A simple layout is ‘simply beautiful.’ One of the most common esthetical mistakes designers make (both professionals and amateurs) is adding too much ‘stuff’ to their designs. A simple, clean layout is almost always more attractive for visitors. Use a concise palette of colours, keep decoration to a minimum, and let your content speak for itself, and you’ll have not only an efficient design but an attractive one as well.

3.2 Required Content Guidelines

• Validate Your Code

  Every single page of the [client] Web site must validate as XHTML 1.0 Transitional. Use the validator tool to check each page you add to the site and fix any errors the validator picks up. See section 1.0 to learn more about validation.

• Stay Within the Required Width

  The content area of the [client] Web site is exactly [500] pixels wide. All content must fit within this width. This means you may not have graphics, tables, or other objects which are wider than [500] pixels.

• Do Not Specify Fonts

  The guidelines of your organization for Web sites clearly specify that sites must use the [Verdana] font for all content. The style sheets for the site already specify this font combination for you, so you do not need to specify fonts at all. If you want to add meaning to your text—like using headers, bold text, italics, etc.—use the appropriate tags as outlined in section 2.0. Never use HTML or CSS to specify any font (even [Verdana]) in your code.

• Use Descriptive ALT Text for Images

  ALT text, a required attribute for images, is displayed to a user when the image does not load correctly or to users who are using browsers which do not display images (such as screen readers for the blind). For images that convey meaning or have text in them, clearly describe the content of the image in the ALT text. For example, a graphical title should have ALT text that reads exactly the same as the title.

  Images that are solely used as decoration and that do not have any meaning should have an empty ALT: <img src="decorative.gif" width="2" height="3" alt="" />

3.3 Best Practices for Content

• Use Textual Headers

  Using text for the heading of your page is quick-loading and consistent with the across the entire Web site. Although it’s tempting to use graphical headers for your pages (and you may notice some existing pages have graphical headers), it is strongly recommended to use textual headers for your content. Use the <h1> <h2> <h3> <h4> <h5> and <h6> tags to mark your headers. See section 2.1 for more information.

• Keep Image Sizes Minimal

  When we talk about image size, we mean the file size, not the physical size of the image. The larger the size of the file, the longer it takes a visitor to download it. Use the appropriate format, GIF or JPG, for the type of image you’re saving and use your image editors settings to reduce the file size as much as possible while still maintaining professional looking quality.

• Clearly Label Special Links

  Hyperlinks to unusual pages should be indicated clearly for the user. Links to PDFs, links that open email messages, links to outside Web sites, and anchor links within a page, are all special situations that should be clearly marked for the visitor. It is confusing if someone clicks on a click and he or she is expecting to go to another page when an email opens instead. Use text next to the link to mark these special instances. Anchor links should have the class “anchor” in the link tag:

  <a href="#top" class="anchor">go to the top</a>

  Bad Examples:

  • View the annual report for 2003.
  • Contact us at any time with your questions.

  Good Examples:

  • View the annual report (PDF file, 230Kb) for 2003.
  • Contact us at contact@domain.com at any time with your questions.

• Keep Content Length Reasonable

  In general keep the amount of content on any single page to a reasonable limit and divide your content into short, labeled paragraphs. Visitors should not be forced to scroll vertically beyond a reasonable amount to view content. As a rough rule of thumb, visitors browsing at a resolution of 800x600 should not have to scroll more than six page lengths. Also, try to divide your content into short paragraphs so that visitors can quickly scan the content for relevant material. Using sub-headers to label sections on the page helps users scan quickly as well. Of course, both of these rules are vague and there will be exceptions to both. Keep them in mind as a rule of thumb and design accordingly.

• Avoid Use of Flash and similar Technologies

  Interactive multimedia tools that require plug-ins should be avoided. Tools like Macromedia’s Flash or Shockwave, Java applets, or other web-based software have serious accessibility issues and require some users to download special software to make use of them. It is very tempting to use these technologies for special presentations, games, and other entertainment content, but the issues surrounding their accessibility for users far outweigh their potential entertainment value. With a bit of imagination, there are more traditional methods of displaying content that, used creatively, can substitute these technologies.