Agile Documentation

Code documentation (and in general Project documentation) is one of the first tasks teams tend to delay as much as possible. We usually think that the most important outcome is to complete the code and have a working application. We do not usually think about who will use, maintain, fix or simply try to understand our code in the future. That's why good documentation will help others (and even ourselves) to avoid wasting time and frustrations trying to reuse or improve existing code.

Technical documentation does not mean writing large and boring documents. Actually, if we want to be good programmers, we need to write documentation that improves the design of our code and let other to learn about the project. Agile methodologies are an excellent way to optimize the development of our applications using iterations. Likewise, they are an efficient way to write technical documentation. We can write small pieces of documentation iteratively instead of waiting until the end of the project to write everything. That way we will know and write the details we need at any moment and will not miss important contents if we try to remember everything later.

Scott Ambler has an excellent post where he describes best practices to write agile documentation:

  • Writing

    • Prefer executable specifications over static documents
    • Document stable concepts, not speculative ideas
    • Generate system documentation
  • 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
  • Determining What to Document

    • Document with a purpose
    • Focus on the needs of the actual customer(s) of the document
    • The customer determines sufficiency
  • Determining When to Document

    • Iterate, iterate, iterate
    • Find better ways to communicate
    • Start with models you actually keep current
    • Update only when it hurts
  • General

    • Treat documentation like a requirement
    • Require people to justify documentation requests
    • Recognize that you need some documentation
    • Get someone with writing experience

See the complete details of the post here: Scott Ambler, Best Practices for Agile Documentation