Practices and principles for an economic documentation

Intro - Agile principles and practices for documentations are responses to the waste, ineffectiveness or even lack of feasibility of traditional approaches such as BRUF – Big Up Front Requirements, BRUD – Big Up Front Design, and to so called “comprehensive documentation”.  We will try  to enumerate and comment here these principles and practices.

Observations – This article is not intended to address also cases where requirements are subject to specific compliance and regulatory environments. Also are out of current post scope some more specific practices like Product Backlog, User Stories or Effective Use Cases.

KISS principle - “Keep It Simple Stupid” - was introduced by Kelly Johnson, system and aeronautical engineer. Unnecessary complexity is “stupid” in a context where complexity it is already an inherent problem. The software domain is one where the unnecessary complexity is a fundamental problem. Here is an example of a software related interpretation: (by Filip Hanik)

https://people.apache.org/~fhanik/kiss.html

Requirements will be changed (!) because of a multitude of reasons: clarifications, business changes, customer understanding changes and others. In such conditions, any comprehensive documentation will require a significant effort of change and in the same time a high risk of not being updated. The first solution is to keep the requirements representation lightweight. That was very clearly said by Robert C. Martin in its book “UML for Java Programmers” (Chapter 5 - Use Cases): “The real trick to use cases is to _keep them simple_. Remember, tomorrow they are going to change” (why requirements as use cases? and why use cases in a programming book? Please discover yourself in the book, or wait for a later post).

 YAGNI principle – “You aren't gonna need it” principle was introduced by XP founders and it is described by Ron Jeffries as: "Always implement things when you actually need them, never when you just foresee that you need them.". That was translated in XP practice “no functionality is added early”.

A good insight about Yagni (and its origins) could be found here: http://martinfowler.com/bliki/Yagni.html 

Martin Fowler states that “only applies to capabilities built into the software to support a presumptive feature, it does not apply to effort to make the software easier to modify.” (For deeper considerations about the last part see Clean Coders series of Robert C. Martin.

Speaking of documentation, you should not “capture” presumptive features, but rather wait until you have good enough information, that mean right balancing between Envisioning and Just In-Time.

TAGRI principle - They Ain't Gonna Read It principle was explained by Scott Ambler here:

 http://www.agilemodeling.com/essays/tagri.htm .

The start idea was that “documentation was written and then ignored by the intended audience”. To avoid this problem, Scott propose more rules. Here are some of them: “Create documents with a clear audience”, “Work with the true audience to identify their actual needs”, “Write agile documentation”.

Documentation it is witted with the intention of being used and used effectively and efficiently. Something is very wrong if the TAGRI is manifesting.

Agile Documentation – a more robust work about effective and efficient documentation for software development is included in Agile Modeling and Disciplined Agile methods. Here are some recommended readings:

Agile Documentation - http://agilemodeling.com/essays/agileDocumentation.htm . Some interesting topics:

• What is the relationship between documentation and project success?
• What Are The Issues Associated With Documentation?
• What Does it Mean to Travel Light? 
• Recommended practices to increase agility of the documentation

When we should document

• http://www.disciplinedagiledelivery.com/agile-documention-strategy/

Agile Modeling Practices for documentation

• Executable Specification – by using TDD, your tests become in fact detailed specification, in a language that is known by the programmer. One of the problems is to know the differences between the flows (what you build) and the scenarios (what you run or test) from coverage point of view. 
• Single Source of Information – it is the equivalent of DRY (Do Not Repeat Yourself) for documentation. One typical example is to duplicate the requirements specs in the test specification. Duplication are definitely not Agile and not Lean. 
• Document Continuously – in Agile we start usually with an Envisioning and continuously to refine it during each iteration. 
• Document Late – a good Agile strategy is to wait until the information is stabilized. Detailed information is rather captured on JIT -Just In Time bases. Also we need to fill the gaps in overview documentation that it is necessary to for the team in the future work on the product.

Important: We can have lightweight requirements documentation in an Agile process only because, in fact. we have also the Executable Specification.

Still … something is missing – To be continued.