O que faz pensar na questão sobre qual e quanta documentação é que é precisa.
Coloquei esta questão ao Mitch Lacey numa entrevista que lhe fiz no início deste ano. A resposta pode ser vista aqui. No entanto, ao ler o livro Agile Database Techniques reparei numa secção sobre documentação que achei muito interessante.
Aqui está um resumo (em inglês)
Documentation is an intrinsic part of any system. The creation and maintenance of which is a "necessary Evil". Liek agile models, agile documents are just barely good enough.
A document is agile when it meets the following criteria:
- Agile documents maximize stakeholder investment- The benefit provided by an agile document is greater than the investment in its creation and maintenance.
- Agile documents are "lean and mean" - They contain just enough information to fulfill its purpose, in other words it is as simple as it can possibly be. Bullets form is allowed. Content is more important than representation.
- Agile documents fulfill a purpose- They fulfill a single defined purpose. If you don't know why you are creating the document, or the purpose is questionable, then stop and rethink what you are doing.
- Agile documents describe information that is not likely to change- The greater the chance that information will change the less value there is in investing significant time writing about it.
- Agile documents describe "good things to know"- They capture critical information, information that is not readily obvious.
- Agile documents have a specific customer and facilitate the work efforts of that customer - A document written for maintenance developers is different from user documentation or tutorial. Work closely with the customer for your documentation if you want to create something that will meet their needs.
- Agile documents are sufficiently accurate, consistent and detailed - Agile documents don't need to be perfect, they just need to be good enough.
- Agile documents are sufficiently indexed - Documentation isn't effective if you cannot easily find the information contained in it.
From the book Agile Database Techniques: Effective Strategies for the Agile Software Developer (Wiley Application Development) (Paperback), by Scott Amber