Page History

I have not had th e the time to really read this or do any further research but wanted to add this.

Best practices for increasing the agility of documentation:

...

Best practices for increasing the agility of documentation:

1. Writing
   • Prefer executable specifications over static documents
   • Document stable concepts, not speculative ideas
   • Generate system documentation
2. Simplification
   • Keep documentation just simple enough, but not too simple
   • Write the fewest documents with least overlap
   • Put the information in the most appropriate place
   • Display information publicly
3. Determining What to Document
   • Document with a purpose
   • Focus on the needs of the actual customers(s) of the document
   • The customer determines sufficiency
4. Determining When to Document
   • Iterate, iterate, iterate
   • Find better ways to communicate
   • Start with models you actually keep current
   • Update only when it hurts
5. General
   • Treat documentation like a requirement
   • Require people to justify documentation requests
   • Recognize that you need some documentation
   • Get someone with writing experience
     

1.Best Practices for Writing Effective Documentation

The following practices will help you to improve your approach to writing documentation:

1. Prefer executable specifications over static documents
2. Document stable concepts, not speculative ideas
3. Generate system documentation
   
4. Simplification
   • Keep documentation just simple enough, but not too simple
   • Write the fewest documents with least overlap
   • Put the information in the most appropriate place
   • Display information publicly
5. Determining What to Document
   • Document with a purpose
   • Focus on the needs of the actual customers(s) of the document
   • The customer determines sufficiency
6. Determining When to Document
   • Iterate, iterate, iterate
   • Find better ways to communicate
   • Start with models you actually keep current
   • Update only when it hurts
7. General
   • Treat documentation like a requirement
   • Require people to justify documentation requests
   • Recognize that you need some documentation
   • Get someone with writing experience
     

1.Best Practices for Writing Effective Documentation

The following practices will help you to improve your approach to writing documentation:

1. Prefer executable specifications over static documents
2. Document stable concepts, not speculative ideas
3. Generate system documentation
   

1.1 PreferExecutable Specifications Over Static Documents

The majority of the information captured in traditional specification documents, such as requirements specification, architecture specifications, or design specifications, can be captured as "executable specifications" in the form of tests.  When you take a Test-Driven Development (TDD) approach you effectively write detailed specifications on a just-in-time (JIT) basis.  With TDD you write a test, either at the customer/acceptance level or the developer level, before writing sufficient functionality to fulfill that test.  The tests are used for two purposes: they specify the requirements/architecture/design and they validate your work.  This is an example of the practiceSingle Source Information.

1.2Document Stable Concepts, not Speculative Ideas

As you see inFigure 1, the agile strategy is to defer the creation of all documents as late as possible, creating them just before you need them via a practice called "document late".  For example, system overviews are best written towards the end of the development of a release because you know what you’ve actually built.  Similarly, the majority of user and support documentation is also best written towards the end of the lifecycle.  However, this doesn't mean that all documentation should be left towards the end.  You might still want to take notes for these sorts of documents throughout development so that you don't lose critical information.  These notes may be nothing more than point-form information as there is no need to "polish" documents until just before final delivery of them.

Figure 1*. Documentation throughout the software development lifecycle.*

By waiting to document information once it has stabilized you reduce both the cost and the risk associated with documentation.  Cost is reduced because you won't waste time documenting information that changes, which in turn motivates you to update the documentation.  Risk is reduced because there is significantly less chance that your existing documentation will be out of date.  If you write documentation containing information which has not yet stabilized then you are at risk of having to rework the documentation once the information has changed.  In other words, you do not want to invest much time documenting speculative ideas such as the requirements or design early in a project.  Instead, wait until later in the lifecycle when the information has stabilized and when you know what information is actually useful to you.  The implication is that your documentation effort may be a few iterations behind your software development effort.

An extreme version of this practice is to wait until you are finished and then write the documentation, the primary advantage being that you are writing about a known and stable thing (the release of the software that you just built).  There are clearly several disadvantages to this approach:

• You have likely forgotten some of the reasons behind the decisions that you made, clearly a problem if this is important to you.
• You may not have the right people anymore to write the documentation because they've moved on to other projects.
• You may not have funding to do the work.
• The will to write the documentation may no longer exist. 
  

1.3Generate System Documentation

Modern software-based modeling tools can reverse-engineer existing code and present a multitude of views into it.  In short, you can save significant money by generating the majority of the system documentation that you need.

2.Best Practices for Simplification

The following practices will help you to simplify the documentation that you write:

1. Keep documentation just simple enough, but not too simple
2. Write the fewest documents with least overlap
3. Put the information in the most appropriate place
4. Display information publicly
   

2.1 Keep DocumentationJust Simple Enough, but not Too Simple

1.1 PreferExecutable Specifications Over Static Documents

The majority of the information captured in traditional specification documents, such as requirements specification, architecture specifications, or design specifications, can be captured as "executable specifications" in the form of tests.  When you take a Test-Driven Development (TDD) approach you effectively write detailed specifications on a just-in-time (JIT) basis.  With TDD you write a test, either at the customer/acceptance level or the developer level, before writing sufficient functionality to fulfill that test.  The tests are used for two purposes: they specify the requirements/architecture/design and they validate your work.  This is an example of the practiceSingle Source Information.

1.2Document Stable Concepts, not Speculative Ideas

As you see inFigure 1, the agile strategy is to defer the creation of all documents as late as possible, creating them just before you need them via a practice called "document late".  For example, system overviews are best written towards the end of the development of a release because you know what you’ve actually built.  Similarly, the majority of user and support documentation is also best written towards the end of the lifecycle.  However, this doesn't mean that all documentation should be left towards the end.  You might still want to take notes for these sorts of documents throughout development so that you don't lose critical information.  These notes may be nothing more than point-form information as there is no need to "polish" documents until just before final delivery of them.

Figure 1*. Documentation throughout the software development lifecycle.*

By waiting to document information once it has stabilized you reduce both the cost and the risk associated with documentation.  Cost is reduced because you won't waste time documenting information that changes, which in turn motivates you to update the documentation.  Risk is reduced because there is significantly less chance that your existing documentation will be out of date.  If you write documentation containing information which has not yet stabilized then you are at risk of having to rework the documentation once the information has changed.  In other words, you do not want to invest much time documenting speculative ideas such as the requirements or design early in a project.  Instead, wait until later in the lifecycle when the information has stabilized and when you know what information is actually useful to you.  The implication is that your documentation effort may be a few iterations behind your software development effort.

An extreme version of this practice is to wait until you are finished and then write the documentation, the primary advantage being that you are writing about a known and stable thing (the release of the software that you just built).  There are clearly several disadvantages to this approach:

• You have likely forgotten some of the reasons behind the decisions that you made, clearly a problem if this is important to you.
• You may not have the right people anymore to write the documentation because they've moved on to other projects.
• You may not have funding to do the work.
• The will to write the documentation may no longer exist. 
  

1.3Generate System Documentation

Modern software-based modeling tools can reverse-engineer existing code and present a multitude of views into it.  In short, you can save significant money by generating the majority of the system documentation that you need.

2.Best Practices for Simplification

The following practices will help you to simplify the documentation that you write:

1. Keep documentation just simple enough, but not too simple
2. Write the fewest documents with least overlap
3. Put the information in the most appropriate place
4. Display information publicly
   

2.1 Keep DocumentationJust Simple Enough, but not Too Simple

Comprehensive documentation does not ensure project success, in fact, it increases your chance of failure.  Documentation should be concise: overviews/roadmaps are generally preferred over detailed documentation.  Follow the Agile Modeling (AM) practicesUse the Simplest Tools,Create Simple Content, andDepict Models Simply when creating documentation.  The best documentation is the simplest that gets the job done.  Don’t create a fifty-page document when a five page one will do.  Don’t create a five-page document when five bullet points will do.  Don’t create an elaborate and intricately detailed diagram when a sketch will do.  Don’t repeat information found elsewhere when a reference will do.  Write in point form.  Document only enough to provide a useful context. Start with a document that's minimal Comprehensive documentation does not ensure project success, in fact, it increases your chance of failure.  Documentation should be concise: overviews/roadmaps are generally preferred over detailed documentation.  Follow the Agile Modeling (AM) practicesUse the Simplest Tools,Create Simple Content, andDepict Models Simply when creating documentation.  The best documentation is the simplest that gets the job done.  Don’t create a fifty-page document when a five page one will do.  Don’t create a five-page document when five bullet points will do.  Don’t create an elaborate and intricately detailed diagram when a sketch will do.  Don’t repeat information found elsewhere when a reference will do.  Write in point form.  Document only enough to provide a useful context. Start with a document that's minimal enough for the needs of its customers then augment it as needed.  To determine what is truly the minimum amount of documentation required by my customers I will actively explore how they intend to use the documentation and why they are using it that way. 

...

Technical writers bring a lot to the table when it comes time to write documentation because they know how to organize and present information effectively.  Don’t have access to a technical writer?  Here are some strategies:

• Consider reading and following the advice presented in UnTechnical Writing or taking a night-school course in writing fundamentals. 
• Try writing documentation with a partner, just like there is significant value pair programmingthere is similar value in “pair documenting”. 
• Have shared ownership of all documentation so that multiple people will work on it.
• Purchase text-to-speech software that allows you to listen to what you’ve written, a great way to discover poorly written passages.
  

6. Recommended Resources

to write documentation because they know how to organize and present information effectively.  Don’t have access to a technical writer?  Here are some strategies:

• Consider reading and following the advice presented in UnTechnical Writing or taking a night-school course in writing fundamentals. 
• Try writing documentation with a partner, just like there is significant value pair programmingthere is similar value in “pair documenting”. 
• Have shared ownership of all documentation so that multiple people will work on it.
• Purchase text-to-speech software that allows you to listen to what you’ve written, a great way to discover poorly written passages.
  

6. Recommended Resources