The Agile Modeling (AM) Method

Menu

The TAGRI (They Ain’t Gonna Read It) Principle

Extreme Programming (XP) introduced the YAGNI (You Ain’t Gonna Need It) principle which advises you to not invest time overbuilding software because you likely won’t need the extra functionality anyway, and that the time you spent building stuff that you don’t need could instead have been invested building stuff that you do need. There’s a complementary concept with respect to documentation: TAGRI, They Ain’t Gonna Read It. The basic idea is that very little of the documentation which gets created during software development actually gets read by the actual target audience. Recognizing this, you should model/document with a purpose and create agile documentation which reflects the true needs of the audience for that documentation; the best way to do this is to work closely with the people you are writing the documentation for, when you do that you discover that they may need something completely different than what you originally thought.

The Problem

Anyone who has been in IT for more than a few years, and in particular anyone who has worked in a mid-size to large IT organization, has experienced or heard of a range of instances where documentation was written and then ignored by the intended audience. It’s quite common to see:

  • Initiatives with detailed requirements specifications fail and/or to have the development team ignore portions of the specification because they believe they know better.
  • Detailed architecture documents be created by an architect only to have the developers take their own approach anyway, even when the original architecture was pretty darn good.
  • Detailed test documents created only to be discarded at the end of the initiative because the development team has run out of time.
  • Documents created put on the shelf and ignored after they passed the documentation review.

Here are a few specific anecdotes:

  1. The requirements document that never got to the developers. I have had the pleasure of visiting India many times. Once while I was there I spent time at several organizations discussing with them how to become more agile. Part way through the trip I spent some time with a gentleman who worked for an IT outsourcing service firm. One aspect of his job was to take the large requirements documents provided by their American clients, which were typically hundreds of pages in length, and to summarize them down to something less than ten pages. This summary was then provided to the development team, not the detailed requirements. They did this because they discovered that no matter how well the documentation had been written the problem still remained that the documents were error prone, contradictory, and far too verbose. This in turn led to the wrong software being developed. Experience showed them that by giving the developers the overview document and then having them talk with the client on a regular basis, daily conference calls were common, that they could do a far better job. In short, this CMMI level 4 firm discovered that a significant productivity improvement (SPI) strategy was to reduce requirements documentation, not increase it. Granted, writing this document up front would hopefully have had the benefit that the client settled on a common vision. However, they could still have achieved this same goal without having to write some much documentation (e.g. perhaps they should have just written the 10-page summary to begin with).
  2. The program architecture that wasn’t. Years ago I worked on a very large program comprised of a collection of related teams. There was an common architecture team within this program whose goal was to provide the technical vision for the various development teams. This team actually did a fairly decent job, producing some very good models which they printed out and displayed publicly. They were also available to consult to the teams. Some teams actually worked with the architects and took advantage of the help, some simply ignored the effort believing that it wouldn’t amount to much (these people were pretty much correct), and others actively worked against the effort. Two teams even invested the time to put together their own competing architectures, one of which was incredibly similar to what the official architecture team put together (it took them several months to admit that their private effort had been a complete waste of time) and another which was very different (the official architecture was based on J2EE, this team wanted to go .NET, and spent significant effort politicking for their approach: they eventually lost). In the end, even though there was a high-quality, realistic definition of an architecture in place, management support for the architecture (including a decree to follow it), and support by the architects to the development teams, most developers still refused to take the time to read the documentation.
  3. Documentation after the fact. A few years ago I worked at an organization which built software that fell under the FDA 21-CFR-11 regulations. The short story is that you have to have a defined software process and sufficient documentation in place to show that the development team actually followed the process. The FDA does random audits, and failing such an audit can do very bad things to your market capitalization. This company did have a software process in place but were a bit challenged following it to the letter, mostly because the process wasn’t very good. So, many teams found themselves in the position of once they had delivered the software into production they now had to spend several weeks or months creating the documentation required to make it look like they had actually followed the process. This documentation had nothing to do with the actual software development, its only benefit was to CYA on the odd chance of an FDA audit. Furthermore, the aim of the regulations is not to promote documentation, it’s to reduce the chance of loss of life due to software-related mistakes; documentation after the fact doesn’t further this goal at all.
  4. The software process which wasn’t read. I’ve lost track of the number of organizations that I’ve worked in where someone within IT thought it was a good idea to put together, or better yet purchase and then modify, a detailed software process description. Although this process description is typically pretty good, and the people behind it enthusiastic about it, the IT professionals that it’s given too rarely bother to read it. Experienced people may flip through it, or simply wait for the half-day training course, and new hires may read the overview and specific portions of it the first week on the job. But invariably the process is rarely read during the actual development of software, typically because the IT professionals are in fact highly skilled and don’t feel the need to read the procedures before doing their job. In short, the process definition effort was mostly a wasted investment.

Fundamentally, on many software development initiatives a lot of documents get created that ain’t really needed at all, or more commonly, only very small portions of the documentation is actually required. The anecdotes described above are likely reflections of bigger problems within your overall software process, but by adopting TAGRI you’d at least be on the way to addressing some of the challenges.

The Solution

One of the misconceptions about agile software development is that we don’t write documentation. Nothing could be further from the truth. Agilists write high-value, effective documentation, and yes, in practice that proves to be a lot less documentation than what traditionalists write. We achieve this by following these rules:

  • Write documentation as a last resort. If your goal is to communicate information to others, documentation is one of the worst possible options available to you (see communication on agile teams). When this is the case strive to choose a better strategy, such as face-to-face conversation or a teleconference call.
  • Distinguish between deliverable documentation and interim documentation. Interim documentation should be treated much differently than deliverable documenation. Interim documentation includes such as requirements specifications (or more accurately requirements speculations), design speculations, and team schedules (to name a few). Deliverable documentation may include artifacts such as system overviews, user guides, and operations manuals. Deliverable documents are part of your solution and will be used by your stakeholders once you’ve deployed your solution into production.
  • Create documents with a clear audience. Disciplined agilists model/document with a purpose: they know who the documentation is being created for, what they will do with it, and what they require of it. Without this knowledge you cannot accurately predict what is actually needed, and will therefore be motivated to over document. For example, many traditional development teams will produce comprehensive system documentation which is provided to the team maintaining the system. However, in practice, many maintenance programmers don’t trust the documentation and often skim it to get an idea of where a problem might be, then they dive into the code to fix the problem (or add the new feature, as the case may be). When you observe maintenance programmers in practice, they don’t need, nor want, the majority of the documentation provided to them. When given the choice, my experience is that most maintenance programmers that I know prefer concise, well written system overview documentation (perhaps just a few diagrams and a summary of key decisions), a full regression test suite, and high-quality source code. So why not provide it to them?
  • Work with the true audience to identify their actual needs. The easiest way to know what someone wants from a document is to involve them in it’s creation, which is why Agile Modeling includes the model with others practice.
  • Write agile documentation. There are many reasons to write documentation, some good and some bad, and my advice is that any documentation that you do write should be just good enough for your current situation. Extraneous documentation simply won’t be read, and even if it is you’re wasting the time of the reader.
  • Single source information. When you single source information you strive to record it in one place and one place only. Common examples of this practice within the agile community are the practice of treating acceptance tests as full-fledged requirements and unit tests as detailed design documentation, the tests effectively being executable specifications. The only documentation that you write should be for critical information that you couldn’t capture using other means.

To determine whether it makes sense to create a document, and if so how far to go with it, consider the following questions:

  • Who is going to use this document?
  • How are they going to use it?
  • What do they expect to see appear in this document? In what format?
  • What is the total cost of creating and then maintaining this document?
  • Who is going to pay for this document?
  • What is the total benefit of having this document?
  • What really needs to be said?
  • What is the most concise way of saying it?
  • What is going to happen if the reader needs more clarification?
  • Does an existing document exist that we could fully or partially reference?

 

Acknowledgements

I’d like to thank Steven Mak, Paul Oldfield, and Rick Wood for their input into this article.

Related Resources