Inline Documentation

Inline Documentation

Communicating Design: Developing Web Site Documentation for Design and Planning by Daniel M. Brown

There are three types of documentation:

• User Needs Documentation - Understanding the people using it
  • What you know about the users
  • Conducting testing - Usability test plan and results
• Strategy Documentation
  • Concept models (conceptual structures)
  • Content inventories (scope of content on site)
  • Competitive Analysis (competitive websites)
• Design Documentation - Define the user experience
  • Highlight specific aspects of expertise
    • Wireframes - Structure of each page
    • Flowcharts - detail user/system interaction
    • Site Maps - Structure of overall site
    • Screen designs - the look and feel
  • Site Maps
    • Demonstrate the relationships between the content and functionality in the site's architecture.  They include the concept, information structure and organizational scheme

Designing Web Usability by Jakob Nielson

Screenshots of a site are often used in documentation.  You should focus on the page design and not the browser in the screen shot. 

Add "Just in Time help" to offer tips for the use of various aspects of the page.

The basic rules for online documentation are:

• Make the documentation pages searchable since users only turn to documentation when they have a problem.
• Have an abundance of examples since examples are easier to follow.  This probably most important since examples allow the user to visualize the process.
• Instructions should be task oriented and emphasize how to do things step by step.  The less space used for background information the better because users usually skip that anyway.
• Provide a short conceptual model of the system.  This will often include a diagram to explain how different parts work together.
• Hypertext links should be used to link difficult concepts or the system.  Oriented terms should be linked to a glossary.
• Finally, documentation should always be brief.

Managing Enterprise Content: A Unified Content Strategy by Ann Rockley

Documentation should be written concisely since users tend to scan or browse it.  Succinctly written documentation is easier to scan for the text containing the important pieces of information.

• Bullets or numbered list are easily scanned
• Short tables or columns to display the relationships of the information make the information easy to browse.
• You need to have white space but not too much.
• Use subheadings to break up the information and make it easier to scan
• User short paragraphs (3-6 sentences) and keep the sentences simple
• Use a consistent design for similar types of information.
• Be short and precise and layer information if there is more information than can be covered in one screen or topic.  Use links to additional windows.
• Make your titles useful.  These can be used as keywords for searching.
• Provide continuity/connection - Refer to the preceding or following processes with links to the processes.
• Use specific references rather than "See figure below..." - Refer to figures, graphics, or tables by name or link to them in secondary windows.

For paper:

• Make the document's purpose obvious and clear.  Have a clearly defined purpose, audience, and context.
• Have one central idea per paragraph or section and make the central idea cleaer right away.
• Put the information into manageable pieces.  This makes it easier for the users to scan, read and comprehend.
• Use headings to tell the purpose of the information in the paragraph.
• Write in a clear and concise language.  Avoid using jargon, legalese, and foreign phrase.

All of the rules for paper documentation also apply to online documentation.  The primary thing to remember is to keep it short and simple if you want the users to use it.