Design Notes

Authoring Tools

All technical documentation is hand coded and compiled with the following tools:

• Microsoft Visual Studio 2005 Team Edition with Service Pack 1:
  • (X).H.T.M.L. source code editor
  • C.S.S. source code editor
  • JScript source code editor
  • Visual Studio 2005 S.D.K. Help Integration Wizard (.HxS conversion)
  • Visual Studio 2005 Integrated Development Environment (I.D.E.) Solution Explorer (MSHelp2 .exe and .msi build process)

• Helpware FAR HTML:
  • MSHelp1 (.chm construction incorporating Microsoft H.T.M.L. Help Workshop)
  • MSHelp2 (.HxC and .HxS construction)
  • Uncompiled Help (web-based help construction)

• Adobe Acrobat Professional:
  • Print-based documents, books, and collections

• Adobe Photoshop and Paint.NET (Beta)
  • Image creation

• SnagIT
  • Image and page capture

top

Metadata

The following elementary metadata is included at the beginning of all web pages:

• As per the H.T.M.L. 4.01 Specification:
  • DOCTYPE = H.T.M.L. 4.01 Strict
  • M.I.M.E./media type = text/html
  • charset="utf-8"
  • lang="en"
• As per the X.H.T.M.L. 1.1 specification (if H.T.M.L. is to be written as X.M.L.):
  • DOCTYPE = X.H.T.M.L. 1.1
  • M.I.M.E./media type = application/xhtml+xml
  • charset="utf-8"
  • xml:lang="en"
    • If the addition of X.M.L. namespaces and content such as S.V.G., ChemML, MathML, etc. into a web document is required, that web page is written with X.H.T.M.L. 1.1. structural markup and conventions.
    • This takes advantage of the modular capbilities of X.H.T.M.L, enabling the incorporation of various X.M.L. namespaces and content within a web document.
    • It should be noted that the rendering of these X.M.L. namespaces and their content within an X.H.T.M.L. document is not well supported by most modern graphical browsers.
    • As an authoring rule I write H.T.M.L. 4.01 Strict markup with its conventions except in the above mentioned case.

top

Construction

Viewing web page markup, presentation and script code

Please feel free to:

• right-click on a web page in your browser asnd view its markup source code.
• open an external C.S.S. style sheet in your help authoring tool or text editor and view its code
• open an external unobtrusive DOM/JavaScript file in your help authoring tool or text editor and view its code

Structure Layer

The markup code and the content comprise the Structure layer of each web page.

• Source order of the structure is preserved in the following hierarchical fashion:
  • Masthead
  • Navigation
  • Content
• This format is followed to aid text browsers and assistive devices in rendering the structure in a hierarchical, top to bottom layout.
• This is also important if styles are turned off in a graphical browser.
  • With styles turned off, a graphical browser will render the markup structure and content in its source order from top to bottom, as does a text browser or assistive device.

All markup elements, attributes and their values adhere to semantic and accessible guidelines as prescribed by their respective W.3.C. Recommendations and U.S. Government Section 508 Rules of the A.D.A.

• There is only one h1 element per web page, and no other heading elements (h2, h3, h4, etc.) preceed it.
• Tabular Data Table elements <table></table> only contain tabular data, and are not used for layout purposes.
  • When employed, all tabular data tables contain:
    • a summary attribute
    • a caption element
    • scope attributes - col and row
    • table header elements
    • table row elements
    • table data elements
    • a table body element
    • a table head element
    • a table foot element (optionally when needed)
    • attributes with appropriate values applied when and where necessary
• Divisions of a web page are controlled by block-level <div></div> elements with appropriate attributes and their values.
• Inline sections (when needed) are controlled by <span></span> elements with appropriate attributes and their values.
• Paragraph, list, etc. elements are employed where they are semantically correct, according to the type of content they contain.

Presentation Layer

Styles applied to browser and print version rendering are controlled by two external Cascading Style Sheets (C.S.S.) and linked to each web page in the head element of the metadata section:

• master.css
• print.css

Presentation is based on the C.S.S. 2.1 Liquid Box Model.

• For example, part of the the Navigation section properties are float: left and position: absolute.

Behavior Layer

When needed, Unobtrusive DOM/JavaScript is employed to enable client-side user action.

• Its unobtrusive nature keeps this layer separate from the structure and presentational layers.
• All scripts are externally linked in the head element of the metadata section of the web page requiring the behavior.

Cross-browser Testing and Markup/C.S.S validation

All web documents are cross-browser tested in:

• Microsoft Internet Explorer (Trident-based)
• Mozilla Firefox (Gecko-based)
• Opera
• Safari for Windows (latest Beta)

Also, web pages and external cascading style sheets are tested online with their respective W.3.C. Validator tools.

• Please see the References topic for external hyperlinks to these validator tools.

top

Navigation

Accessible Global Navigation

I try to incorporate as many aspects of web accessibility into my technical documentation as possible. This is particularly important in the construction and rendering of the navigation section of each web document. Below you will see different methods employed to help all users easily recognize, understand, and effectively use this tool.

• The first item in the navigation section is the SKIP TO CONTENT button.
  • This is an accessibility tool enabling users working with assistive devices to go directly to the content in a web page. This is normally the first subtopic.
  • It allows a user to avoid the repetitive reading of the navigation section each time a page is opened.

• The existence of a hyperlink is identified in two ways:
  1. Each hyperlink is styled with bold characters making it easier to see.
  2. Each active or live hyperlink is underlined to visually identify it.
     1. An active or live hyperlink is one that is enabled to reach its named destination.

• Important Note on the use of underlining:
  • Underlining is applied as a:
    • solid underline - Identifies an active hyperlink
    • dashed underline - Identifies an acronym
  • Underlining is not employed anywhere to achieve a presentational or stylized effect.

• Hyperlink states are employed to help users identify their navigation actions and options:
  • It increases the accessibility of the navigation, especially for color-blind users who may not be able to see the color difference between a visited, unvisited and active hyperlink.
    • Accordingly, an icon representing the state of the hyperlink is shown, enabling users to visibly know if they have or have not visited a page.
  • The state of a hyperlink is identified in three ways:
    1. The color of the hyperlink changes appearance according to its state:

       Hyperlink State by Color

       Hyperlink State	Related Color
       unvisited	blue
       visited	orange
       hover	white
       active	blue
       focus	blue
       currently open	yellow

    2. An icon to the right of the hyperlink changes appearance according to its state:

       Hyperlink State by Icon

       Hyperlink State	Related Icon
       unvisited
       visited
       hover

    3. The hyperlink of a page that is currently open (being viewed):
       1. is colored yellow
       2. the link is disabled
       3. no icon is present

• For your guide, this navigation scheme is built with (X.)H.T.M.L. structured markup and an external C.S.S presentation style sheet (master.css).
  • There is no DOM/JavaScript involved in its creation.
  • An upcoming Fast Track tutorial will demonstrate how this is done.

Accessible Subtopic Navigation

Subtopic navigation for a page is placed directly above the global navigation TOPIC section. They are listed under the ON THIS PAGE.... heading.

• Subtopic page navigation incorporates all of the techniques applied to global navigation, as described above.

Content Section Hyperlinks

Hyperlinks in a Content section mirror the same effects as in the Global and Subtopic schemes except for the Visited state.

• The Visited state is colored purple as per a normal browser visited link.
• This is because the color orange does not give enough visual contrast when set against a white background.

top