Style Guide - Code and Presentations

Style Guide for Writing HTML Code

Equally as important as designing a well organized web presentation is the practice of creating well designed HTML documents. Two primary reasons for keeping HTML documents consistently constructed are:

• 30 to 35 per cent of all web users use some form of text-only browser or have image loading disabled on their browser for faster access. Some of these users receive the document in its raw form and must view the contents in the midst of the HTML code.
• Maintenance and updating a well-organized document is much easier and more efficient than one which is cluttered and unorganized.

The following practices are required for all HTML code handed in for assignments and tests.

1. Unless absolutely required by the behaviour of the Element tags (such as preformatted text), text must be separated from the tags to enhance readability.
2. When nesting various tags within other tags, indent each nested set whenever possible to clearly show which tag sets belong together.
3. Keep start and end tags organized by either leaving spaces between the first and last characters on the line, such as with headings, or by aligning the tags vertically to clearly show the scope of the element, such as with lists.
4. Only nest elements within other elements if allowed under the HTML DTD. And end the innermost element before ending an out element.

   Use this:

   <BLOCKQUOTE>
       <ADDRESS>
          <B>  Website Design Course  </B>
   
          <P>
            <B>
               Bill Cassidy            <BR>
               St. Lawrence College    <BR>
               Kingston, Ontario       <BR>
            </B>
       </ADDRESS>
   </BLOCKQUOTE>
   

   Instead of this:

   <ADDRESS>
        <BLOCKQUOTE>
          <B>  Website Design Course
   
          <P>
               Bill Cassidy            <BR>
               St. Lawrence College    <BR>
               Kingston, Ontario       <BR>
          </B>
       </ADDRESS>
   </BLOCKQUOTE>
   

5. Do not use an element for something other than the purpose for which it was designed. For example, headings were meant to be headings.
6. Always include a TITLE for your document in the HEAD section.
7. Always provide ALTernative text for images.
8. Use comments sparingly!
9. Include the following META tags in each HTML document handed in for assignments:

     <META NAME="Author"      CONTENT="Your Name">
     <META NAME="Date"        CONTENT="Date Assignment Due">
     <META NAME="Description" CONTENT="CIS500 - Assignment # n">
         

Style Guide for Presentations

Structure

Here are a number of issues to keep in mind when designing an effective web presentation.

• Always keep your audience in mind.
• Consider how your prospective audience views the structure your topic.
• Design your presentation so the user doesn't "get lost"
  • Provide clear navigational links
  • Provide a link to your home page or index on every page
  • Possibly provide a site map if your presentation is quite large
• Make links meaningful. Don't link for the sake of linking!
• Use graphics only when relevant. Graphics images often take longer to download and are not accessible to everyone.
• Avoid the Times Square syndrome!
• The latest technology may provide useful tools, but don't automatically employ them for the sake of using the latest fad. Only use what you need.
• Keep in mind download time. The larger your files (and the larger the quantity), the longer it takes to download.
  • 15 to 20 seconds is usually the longest a user will wait before linking off to somewhere else.
• Keep individual documents a reasonable length. Usually no more than 4 to 6 "screens" per document, especially at the upper levels of a presentation. Remember the user on a text-based terminal, not a PC!
• When creating links to external sources, verify that they are currently valid, and check them regularly.
• Add a "signature block" to your documents.
  • Place a link at the bottom of the page to either your personal home page or your e-mail address.
  • Provide other contact information, such as mailing address or phone, where appropriate.
  • Provide a Creation/Last-Modified date (if your server doesn't) to let users know the information is up-to-date.
• Individual pages should either stand alone as well as part of the whole presentation, or atleast provide a good indication of its context in case someone else has provided a link to a page somewhere within your presentation, rather than the beginning.
• Make TITLEs informative and less than 64 characters in length.
• To maintain platform-independence and make presentations "browser-friendly", always use elements in the way in which they were intended and avoid browser specific terminology.
  • For example, use heading elements in decending order within each document. Level 1 at the top, followed by Level 2 headings, then Level 3, if required. Don't skip from Level 1 to Level 3, not using Level 2. This may cause problems in some browsers.
  • Don't over-use line breaks and spaces, this can reak havoc on some browsers.
  • Don't write: "Click Here" for a link, or any other browser specific terminology. Clicking on a link is only possible if you have a mouse! Users generally know how to activate links, and newbies learn fast.
• Don't design your presentations to your particular browser and computer configuration. Design in terms of structure, rather than "local" appearance.
• Design pages to be printable whenever possible, or provide a link to a printable version.
• Make your (hyper)text readable

  This is just a little rant about two style issues in hypertext that I'm [Tim Berners-Lee] seeing more of and don't like much.

  The first is the _here_ syndrome, eg.:

  Information about Blah Blah Blah is available by clicking _here_.

  where the word _here_ is the link. This style is really awkward; when you click on 'here', you have to look around to make sure it is the *right* here. Let me urge you, when you construct your HTML page, to make sure that the thing-you-click is actually some kind of title for what it is when you click there. E.G. say

  Information about _Blah Blah Blah_ is now available.

  And use:

  Information on _how to do searches_ is available.

  Instead of:

  For information on how to do searches, choose _this link_.

  Not quite as bad, but still awkward is where someone will use a topic word as a link, but it still talks about the links:

  Here are links to a _CREDITS_ page and _technical details_ ...

  Instead, try writing something like

  Many thanks go to _various people_ for the contributions.
  _Technical details_ of this system are available now.

  I.e., make your HTML page such that you can read it even if you don't follow any links.

  -- excerpt from Style Guide for online hypertext
  - Tim Berners-Lee

• Be honest - indicate whether your presentation is biased (especially when creating a commercial presentation).
• Create a text-only version, if necessary, to accomodate text-only browsers.

This listing is far from complete, but provides a good starting point for developing effective web presentations.

Home Page | Session 3 Index | Public Identifiers | Design Principles