General Information

Documentation is an important part of agile software development.  It needs to be as efficient as possible and is best written toward the end of the iteration.  Throught the development of the iteration, notes should be taken in order to remember why you did what you did.

It should be kept simple and concise.  Detailed documentation is harder to maintain and is more likely to contain errors.  As a result, your documentation should be an overview keeping in mind how the customer will be using it.

• 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.

Documentation should be "just barely good enough".  Keep in mind that the customer will probably skim the document rather than reading it in its entirety.  For this reason, it should be designed as a main document with links to other documents.  Remember that it should not be technical.  In order to avoid this, you should work with someone when writing it in order to get feedback as it is being written.  This ensures that it meets the needs of your customer.  Some questions for the customer should be:

• What they do
• How they do it
• How the want to use the documentation

Inline Documentation

For inline documentation, there are some basic rules:

• 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.

screen shots and help tips are often used for online documentation.  As always, it should be concise and easy to scan.  In order to achieve this:

• 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.

Notes and Sources used to create this document:

Agile Documentation

Inline Documentation

Writing Documentation