Extreme Programming (XP) introduced the YAGNI (You Aren'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 Aren'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:

• Projects 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 a project 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 project 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.  In the spring of 2005 I had the pleasure of visiting India.  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 projects.  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 project 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 project 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 projects a lot of documents get created that aren'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:

• Treat documentation like any other requirement.  Any document, even if it's IT related, should be costed, prioritized, and treated like any other system requirement.  This will help you to quickly identify the documentation that provides value, and more importantly will focus your efforts to ensure that you do just enough documentation.
• Create documents with a clear audience.  Agile modelers 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? Who is going to pay for 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.

Recommended Resources

		Agile Modeling: Effective Practices for Extreme Programming and the Unified Process is the seminal book describing how agile software developers approach modeling and documentation.  It describes principles and practices which you can tailor into your existing software process, such as XP, the Rational Unified Process (RUP), or the Agile Unified Process (AUP), to streamline your modeling and documentation efforts.  Modeling and documentation are important aspects of any software project, including agile projects, and this book describes in detail how to elicit requirements, architect, and then design your system in an agile manner.
		Agile Documentation describes a collection of patterns for writing effective system documentation.
		The Object Primer 3rd Edition: Agile Model Driven Development with UML 2 is an important reference book for agile modelers, describing how to develop 35 types of agile models including all 13 UML 2 diagrams.  Furthermore, this book describes the techniques of the Full Lifecycle Object Oriented Testing (FLOOT) methodology to give you the fundamental testing skills which you require to succeed at agile software development.  The book also shows how to move from your agile models to source code (Java examples are provided) as well as how to succeed at implementation techniques such as refactoring and test-driven development (TDD).  The Object Primer also includes a chapter overviewing the critical database development techniques (database refactoring, object/relational mapping, legacy analysis, and database access coding) from my award-winning Agile Database Techniques book.
		The Elements of UML 2.0 Style describes a collection of standards, conventions, and guidelines for creating effective UML diagrams. They are based on sound, proven software engineering principles that lead to diagrams that are easier to understand and work with.  These conventions exist as a collection of simple, concise guidelines that if applied consistently, represent an important first step in increasing your productivity as a modeler.  This book is oriented towards intermediate to advanced UML modelers, although there are numerous examples throughout the book it would not be a good way to learn the UML (instead, consider The Object Primer).  The book is a brief 188 pages long and is conveniently pocket-sized so it's easy to carry around.

Let Us Help

We actively work with clients around the world to improve their information technology (IT) practices, typically in the role of mentor/coach, team lead, or trainer.  A full description of what we do, and how to contact us, can be found at Scott W. Ambler + Associates.