Information Technology Policies and Standards

Title
Web Document Structure
Type
Standard
Related Policy
Purpose & Commitment to Quality Policy
Category
Web
Status
Withdrawn
Approved
02/17/2005
To Be Reviewed
02/17/2007
Scope
This standard ensures a consistent appearance for web pages. It deals mainly with static HTML documents, but dynamically rendered pages and alternative formats (e.g. PDF) should follow the same conceptual layout standards whenever possible.

Conventions in the standard are based on the OASIS DocBook format. This is an open source SGML standard that describes the structure of a document.
Standard
To provide a consistent look and feel across all web pages, designers shall implement pages using the following conventions (see image below):

Subject
Every document shall have a subject that defines what the document is about. The subject should be concise and descriptive. The subject must not contain any department names. The subject will be used in 2 ways:
  • It will serve as the primary heading for the page. (In the case of an HTML document, this will be an <H1>tag).
  • The same wording should be used as left hand, secondary navigation (i.e. if the subject is "swim lessons" this wording should be used as consistently as possible in the navigation and title. Not "swimming lessons" or "aquatics for 2004", but "swim lessons". The subject should be short, intuitive, and should not include acronyms.)

Topic
Every document should also belong to a topic. The topic of the document can be determined by asking the question “what single word best describes the category of this document?” (A page/subject on swim lessons, for example, could be classified with a topic of recreation)

File Name
Every document shall have a file name that follows the File Names Standard.

Title
Every document shall have a document title (e.g. <title> tag in HTML). The title shall be in the following format: subject – topic - City of Albuquerque.

Meta-data
If supported by the document format, a static document (such as an HTML page) must contain keyword meta-information. Dynamic documents are exempt from this only if they are temporary in the sense that they are transient pages and will not be indexed by search engines. There may be cross-over in content between wording contained in themes and wording contained in keyword meta-data, however we wish to make a separation between what the document is about and any hints that document gives about being searched. (See also: Search Engine Effectiveness Standard.)

Body Content
A subject / header must not appear in a document unless there is content under it. Likewise, a document must not consist solely of text unless it is prefixed by a heading.

The content immediately following the outermost heading (<H1> in the case of an HTML document) should be an abstract with the following characteristics:
  • Brief (less than 150 words)
  • Contain document key words
  • Describe the rest of the document

In the case of a news item, the news item body may replace the abstract only if the text forming the body of the news item does not consist of any further structural divisions (header tags etc.). If the item body does contain more structural elements, then either the news item must be redacted or the whole page treated as a standard, static HTML page.
  • Documents should follow a nested structure. This means that sub-headers and associated content should always appear after major headers and never before them. As an example, the following snippet of HTML code is valid:
    <body>
    <h1> The Internet and it's Role in Marsupial Communication</ h1>
    <p>This document discusses ways in which the Internet can assist marsupials in the office place</p>
     <h2>Introduction</h2>
    <h3>Intended audience</h3>
    <p>This document is primarily designed for marsupials and mammals such as wallabies and camels</p>
    <h3>Technical Requirements</h3>
    <p>We assume that most marsupials have access to the internet through either broadband or dialup</p>
    <h2>Marsupial communication today</h2>
    <p>This is where we start the discussion.</p>
    </body>

    The following code is structurally invalid:
    <body>
    <h2> The Internet and it's Role in Marsupial Communication</ h2>
    This document discusses ways in which the Internet can assist marsupials in the office place
    <h1>Introduction</h1>
    <h3>Intended audience</h3>
    This document is primarily designed for marsupials and mammals such as wallabies and camels
    </body>
  • If a list describes a consecutive series of steps, then an ordered list <ol/> starting from 1 must be used. If the list describes an arbitrary number of items in which sequence or priority is unimportant, it must use an unordered <ul/> list.
  • Every ordered list must start from 1. This means that a list should never split by a header or other content other than text and then resume with the “next” index number. This prevents fragmentation and makes the document easier to read.


Rationale
The City of Albuquerque is committed to providing information to citizens in an easily read and understood format. There will also be a number of other benefits:
  • Each City page will have a common look and feel. The importance of who “owns” a particular page will decrease and the importance of the content and thematic grouping will increase. The effect of this is to present information as the citizen wants it instead of how the department sees it.
  • Customer Service Reps (CSR’s) will be able to respond faster to citizens’ queries.
  • It will be easier for automated parsing programs to extract information from an HTML page if the page follows a structural standard.
  • Because the document is based on the de facto DocBook standard, pages should have a greater longevity because they can be imported and manipulated into different applications without the need for extensive re-writing.
  • There is more chance that a page will render correctly on a client device if it is well structured.
  • Because a document has a definable structure, it has greater accessibility and should give a better experience to users requiring assistive technologies (e.g. screen readers)
  • Browsers use the title of a document as the bookmark title when creating a new bookmark. A clear title means that it is obvious to the reader what the link refers to.
  • Search results on large search engines will display the title of a document. A clearly structured title will help the reader decide whether this document is relevant.

Contact: Mark T. Leech, (505) 768-3731