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
- Print-based document collections
- Adobe Photoshop and Paint.NET
- Image creation
- SnagIT
- Image capture
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.
Construction
Viewing web page markup, presentation and script code
Please feel free to:
- right-click on a web page in your browser and 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
- When employed, all tabular data tables contain:
- 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 Liquid Box Model method of float and positioning.
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.
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:
- Each hyperlink is styled with bold characters making it easier to see.
- Each focused, hovered, or active hyperlink is underlined to visually identify it.
- A hyperlink may be given Focus using the TAB key on the keyboard, or by using a Mouse to hover over it.
- Important Note on the use of underlining:
- Underlining is applied as a:
- solid underline - Identifies a focused/hovered-over hyperlink
- dashed underline - Identifies an acronym
- Underlining is not employed to achieve a presentational or stylized effect.
- Underlining is applied as a:
- Hyperlink states are employed to help users identify their navigation actions and options:
- It increases the accessibility of the navigation, especially for color-blind, hard of seeing, and quick memory loss users who may not be able to see or remember the color difference
between a visited, unvisited and active hyperlink.
- Accordingly, a symbol 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:
- The color of the hyperlink changes appearance according to its state.
- A symbol to the right of the hyperlink text dynamically changes appearance according to its state.
- The hyperlink of a Currently Open page is disabled.
Hyperlink State by Color, Symbol and Enabled Hyperlink State Related Color Related Symbol Link Enabled? End Table Unvisited blue 
Yes Visited orange 
Yes Focus/Hover white, underlined 
Yes Currently Open yellow 
No
- It increases the accessibility of the navigation, especially for color-blind, hard of seeing, and quick memory loss users who may not be able to see or remember the color difference
between a visited, unvisited and active hyperlink.
- 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. Internal page hyperlinks are listed under the ON THIS PAGE.... heading.
- Subtopic page navigation incorporates all of the techniques applied to global navigation, except for the Currently Open hyperlink state.
Content Section Hyperlinks
Hyperlinks in a Content section mirror the same effects as in the Global and Subtopic schemes except for the Visited and Currently Open states.
- 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.