Last week I talked about one of the ways in which a software development organisation can assess where they sit on an industry-recognised maturity scale, that is: the maturity model set out by the CMMI. For my own efforts, having to do such an assessment myself, I compiled a number of interview questions in order to determine whether or not the required so-called Specific Goals (SG) were being satisfied.
Due to our simultaneously experimenting with introducing a lean/agile mindset in one of our teams, the inevitable face-off between the classic process-oriented philosophy implied by CMMI and the lightweight, waste-eschewing agile approach has come to the fore. The maturity assessment interview questions that I compiled were largely influenced by the CMMI specific practices, subpractices and examples as set out in the official document. I compiled forty questions, and no less than twelve of them contain variations of the word “document” in them.
What do we mean by “Document”?
In its broadest sense, a document is a record of some sort, the essential characteristics being:
- Informational;
- Persistent.
Our reasons for keeping documents on projects are many and varied; Scott Ambler has delved into this question quite comprehensively, but distilling this down, we can classify the reasons as:
- Maintenance of organisational memory (the “good” reason most people think of);
- Because we have to (for audit purposes, or the customer has explicitly requested it);
- In order to make agreements explicit (i.e., contractual).
As Scott points out in his article, one could also be writing documentation in order to “work through something”, for purposes of fleshing the details of a design out, for instance.
Documentation is always intended for human consumption. In contrast, source code is intended for machine consumption; well … that’s partly true; although our primary focus when doing things in an agile manner is the immediate requirement for software, there’s a natural tension between that imperative and supporting the next thing. Along those lines, writing software for the immediate requirement only can be argued to be foolish–there needs to be a balance of some sort.
The Cost of Documentation
Anything that does not result in delivery of value to the customer is waste. Waste is, by definition, that which is of no value. Some things are of absolutely no value, for example a process that is busy occurring, the outputs of which are no longer required. Other things can be argued to be of value, but it’s not immediately clear whether or not they’re value-ful; for instance: a requirements document or a project plan; both such artifacts are deemed to be necessary in order to produce software, but the link is tenuous and the level of value associated with such artifacts is largely a function of human considerations.
It’s easy to understand, though, that documentation that is not directly tied to producing working software has an associated cost of ownership. Writing a document that ostensibly contributes to a software product or application immediately has an indefinite annuity cost as soon as it comes into existence; that’s because in order to be of value it needs to be maintained.
Agile Documentation: The Tenets
In order to support an agile process, it’s generally accepted that there are certain tenets that need to be observed; these are in line with the Agile Manifesto:
- Essence, that is just enough, and only that which is of value.
- Aggressively favour executable over static;
- Only if and when it provides value.
Trying to get documentation to be executable means that it needs to be actively part of the system—this point to me is the most crucial one because it deals with the aspect of documentation that is generally considered to be the reason why projects are more likely to fail. The fact that introducing documentation is tantamount to introducing risk has to do with its disconnected nature–it is disconnected (or tenuously connected) from the delivery of value to the customer. To be sure, it may be connected to delivery of value but if it’s not executable, that call is up to a person, or a group of people—this is where things get fuzzy.
Examples of executable documentation:
- Code;
- Automated tests.
Of the articles that I’ve read on this subject, many (if not all) talk about comments in code. In my opinion comments are an example of documentation disconnected from the delivery of value to the customer and should therefore be avoided. Almost all comments can be represented by narrative code thereby making the documentation part of the mechanics of the product. Occasionally, telling the “how” story in the source code borders on contrived (the effort to do so may significantly exceed the risk associated with introducing “disconnected documentation”); in these situations, if it’s necessary to convey something that will save time when the “next thing” comes along, then it’s OK to use a comment or two.
Back to Maturity
I started writing this post originally to “work through” the issue that has been worrying me, that is, the apparent bias that the CMMI maturity model has towards documentation being at odds with an agile approach.
I’m going to take a leap here and focus on the intent of what is stated within CMMI. Although the word “document” is used when describing processes (as in: “Is the process by which you do X documented?”), can we interpret the word slightly differently in order to address what is needed, but at the same time respect our key value of avoiding waste?
If the key attributes of a document are a) an informational record, b) persistence, then what methods can we employ to satisfy those characteristics without introducing things that are disconnected from the delivery of value to the customer?
Looking at the reasons why we document, business continuity, or maintaining organisational memory is largely a risk-mitigation strategy; that is, an attempt to avoid bus factor completely through thud factor. In an agile setting, this consideration can be addressed by:
- Making sure that there is regular knowledge-sharing between team members;
- Making all processes be reflected by code (e.g., you do a build? Have a look at the build script to see how our environments and release process work);
- Where it really is impossible or highly contrived to do b) above, documenting the essence (and only the essence) and getting the document to delegate to the source code or “talking to a team member” for more detailed information.
Obviously, you can’t do the above effectively without trust, collaboration and discipline; this goes without saying.
The holy grail is to make what we produce to the customer which adds value be self-documenting. That’s all well and fine when we’re talking about artifacts that relate directly to the end product, but what about meta-considerations; for instance: how we reflect on our behaviour for the purposes of improvement? We could write a document that describes that, yes – but that’s precisely what we’re trying to avoid. We can’t write code that is self-documenting in this case, it’s meta after all.
If we take a step back and think about it, how we go about our jobs is sort of like a program. For instance, the practice of getting together on a regular basis to have a retrospective meeting; what determines how we do this; the timing, regularity, structure, decision-making? It’s something that everybody knows (learnt and agreed-upon behaviours) which is executed (metaphor: executable code) by a team (metaphor: execution platform) of people. So, to make the “code” in this case self documenting, it needs to be accessible and understandable. For that:
- Pointers must be available (remember, just the essence), that is, in this case, the what (a retrospective meeting–can be a one-liner on a Wiki);
- A “more information” instruction with the pointer on the Wiki—that is, “just ask a team member to explain the process”.
The integrity of the “documentation” of the process is maintained by ensuring that a high number of people know how it’s done (the whole team) together with the fact that team members trust one another and share a philosophy of collaboration to ensure that they’re always on the same page.
The persistence requirement is also fulfilled by the built-in redundancy of having multiple people share the same knowledge. Short of the entire team being wiped out in a plane (or bus) disaster on their way to a team retreat, the risk of loss of IP is taken care of.
Of course, all of this is assuming a land of rainbows and unicorns where the term “corporate politics” is nowhere to be found in the dictionary—mind you, ye traditional manner of maintaining the integrity of processes by tome is arguably no more resistant to such realities of the corporate world, whilst being more expensive and risky by virtue of the false impression that it creates.
