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)
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:
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
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.
