When I initially started work on Agile Modeling (AM) I wanted to focus solely on principles and practices for effective modeling but quickly discovered that this scope was not sufficient, that I also needed to consider the issue of how to be effective at the creation and maintenance of documentation too. Some agile models will "evolve" into official system documentation, although the vast majority will not, and therefore it is relevant to discuss how to be agile doing so. This article explores agile and lean philosophies towards documentation within IT organizations.

In this article I address the following topics:

1. Critical points
2. Models, documents, and source code
3. Why do people document?
4. What is the relationship between documentation and project success?
5. When does a model become permanent?
6. What are the issues associated with documentation?
7. What does it mean to travel light?
8. When is a document agile?
9. What type of documents do you need?
10. Are agilists actually creating documentation and is it any good?
11. When should you create documentation?
12. When should you update documentation?
13. Effective hand-offs
14. Can templates help?
15. How can you reduce documentation CRUFT?
16. When is documentation the best option?
17. Best practices for increasing the agility of documentation

1. Critical Points

1. The fundamental issue is communication, not documentation.
2. Agilists write documentation if that's the best way to achieve the relevant goals, but there often proves to be better ways to achieve those goals than writing static documentation.
3. Document stable things, not speculative things.
4. Take an evolutionary approach to documentation development, seeking and then acting on feedback on a regular basis.
5. Prefer executable work products such as customer tests and developer tests over static work products such as plain old documentation (POD).
6. You should understand the total cost of ownership (TCO) for a document, and someone must explicitly choose to make that investment.
7. Well-written documentation supports organizational memory effectively, but is a poor way to communicate during a project.
8. Documentation should be concise: overviews/roadmaps are generally preferred over detailed documentation.
9. With high quality source code and a test suite to back it up you need a lot less system documentation.
10. Travel as light as you possibly can.
11. Documentation should be just barely good enough.
12. Comprehensive documentation does not ensure project success, in fact, it increases your chance of failure.
13. Models are not necessarily documents, and documents are not necessarily models.
14. Documentation is as much a part of the system as the source code.
15. Your team's primary goal is to develop software, its secondary goal is to enable your next effort.
16. The benefit of having documentation must be greater than the cost of creating and maintaining it.
17. Developers rarely trust the documentation, particularly detailed documentation because it's usually out of sync with the code.
18. Each system has its own unique documentation needs, one size does not fit all.
19. Ask whether you NEED the documentation, not whether you want it.
20. The investment in system documentation is a business decision, not a technical one.
21. Create documentation only when you need it at the appropriate point in the life cycle.
22. Update documentation only when it hurts.

2. Models, Documents, and Source Code

Figure 1. The relationship between models, documents, source code, and documentation.

3. Why Do People Document?

Agile developers recognize that documentation is an intrinsic part of any system, the creation and maintenance of which is a "necessary evil" to some and an enjoyable task for others, an aspect of software development that can be made agile when you choose to do so. There are several valid reasons to create documentation:

1. Your project stakeholders require it. The creation of documentation is fundamentally a business decision, you are investing the resources of your project stakeholders in the development of the documentation therefore they should have the final say on whether their money is to be spent that way, not a technical one. If your project stakeholders request a document from you, perhaps at your suggestion, and understand the trade-offs involved (more on this later), then you must create the document. It is important to note that eXtreme Programming (XP) is very explicit about documentation being a business decision. You should create documentation only when your project stakeholders ask you to? Preposterous you say! Well, my experience is that this isn't preposterous. Your project stakeholders include a wide variety of people, including all of the clients of your system, and therefore they should have a reasonably good idea what they want. Maintenance developers, or someone representing them if they are not in place yet, will request system overview documentation. Users and their management will likely request user documentation. Operations staff will request operations documentation. Yes, you will need to work closely with them to determine what they actually need, someone is going to have to decide to pay for the development and subsequent maintenance of the documentation, and you may even need to explain the implications of what is being requested, but this is doable.
2. To define a contract model. Contract models define how your system and an external one interacts with one another, some interactions are bi-directional whereas others are uni-directional, making the interaction(s) explicitly to everyone involved. Contract models are often required when an external group controls an information resource that your system requires, such as a database, legacy application or information service. The AM practice Formalize Contract Models states that a contract model is something that both parties should mutually agree to, document, and change over time if required. It is important to understand that the development of a contract model should still be verified by your project stakeholders-it is their money that you are spending, and if they choose to go at risk and not have the contract model in place then that is their choice.
3. To support communication with an external group. It isn't always possible to co-locate a development team and it isn't always possible to have project stakeholders (or at least the ones you need at the time) available at all times. When you need to work with an external group of people you need to find ways to communicate with them, and shared documentation is often part of the solution in combination with occasional face-to-face discussions, teleconferencing, email, and collaborative tools. It is a mistake to use documentation as your primary means of communication because it's far too easy to misunderstand something that has been written, but it is a good supporting mechanism. A good way to think of documentation in this situation is that it is your option of last resort. Note that this in effect is an extension of the practice Model to Communicate into the realm of documentation.
4. To support organizational memory. One of the principles of Agile Modeling is Enabling the Next Effort is Your Secondary Goal which is meant as a counter-balance to the principle Working Software is Your Primary Goal. An important implication is that we not only need to develop software, but we also need to develop the supporting documentation required to use, operate, support, and maintain the software over time.
5. For audit purposes. I've worked in organizations where we've developed life-critical systems, and those systems fell under the auspices of the US Food and Drug Administration (FDA) audit guidelines. I've also worked in organizations where Sarbanes-Oxley (SOX or Sarbox) and/or BASEL-II were applicable. The common theme was that we had to follow a defined process and capture proof that we did so, resulting in more documentation than we would have normally written. In these situations you still want to create just enough documentation to get the job done. A common mistake that I see get made is that the bureaucrats jump on the "We're might get audited by so-and-so, therefore we need to produce the following documentation...". My advice is to read the appropriate guidelines yourself, because they rarely require what the bureaucrats think they require. Be smart about compliance.
6. To think something through. Many people will write documentation to either to verify for themselves some group work they had just been involved with or simply to increase their own understanding. The act of writing, of putting your ideas down on paper, can help you to solidify them and discover problems with your thinking. What appears clear and straightforward in your mind can often prove to be very complicated once you attempt to describe it in detail, and you can often benefit from writing it down first. It is for this reason that I suggest that people write comments before they write their code, a practice that I have been following for years.

This very likely differs from what you are used to doing, which makes sense because I'm talking about how to become more agile in your approach to documentation. Why is this different, and why is it more agile? My experience is that developers in non-agile environments are often forced to create documentation for less-than-ideal reasons, often based on political reasons and sometimes due to sheer ignorance, and therefore may not have been allowed to be as effective as they possibly can. Questionable reasons for creating documentation, and how to combat them, include:

1. The requester wants to be seen to be in control. People will request documents, such as specifications and detailed architecture documents that they can sign off on and say "yes, go ahead and build us one of these." Whenever I find myself in this situation I ask the individual(s) requesting the documents if they also want to be seen as responsible for the project's failure because the development team was too busy focusing on needless documentation and not on building software. I'll then suggest that instead of requesting documentation they should instead request access to the software itself, even if it is just an internal release of the software, so they can provide constructive feedback about it. They can still be seen to be an active participant in the project and can do so in a productive manner.
2. The requester mistakenly thinks that documentation has something to do with project success. Nothing could be further from the truth.
3. The requester wants to justify their existence. This typically occurs when someone who is "dead wood" is desperate to be seen doing something. This is an insidious problem because the requester often has what appears on the surface to be a good reason for requesting the documentation, it's something they've been doing for years, and management often believes it's necessary. To address this problem I will ask the requester what they intend to with the document, why they need it, why creating that documentation for them is more important than other work that my team needs to do, and so on to try to determine the actual value of what it is that they're doing. These are valid questions to ask, albeit uncomfortable ones for someone that doesn't add much value to the development effort.
4. The requester doesn't know any better. Many people have been working in organizations that have been following non-agile processes for years, processes that were likely documentation centric, processes that produced a lot of documents for review throughout the process and finally software at the end of it. This is what they're used to so they are simply asking you for something they've gotten in the past. The idea that you can produce software early in the project, that it's your primary goal, is new and often radical to many people.
5. Your process says to create the document. Although this isn't a problem with agile software processes it definitely can be one with prescriptive software processes. The most common reasons for this problem include people wanting to justify their existence (see above), people not understanding the software development process or at least the implications of what they are requesting, and situations where the primary goal is to bill for hours as opposed to develop software effectively. Once again, the best strategy to address this problem is to explore whether the creation of the document actually provides value to your efforts.
6. Someone wants reassurance that everything is okay. Your project stakeholders are investing significant resources in your project team, they're taking a risk on you, and they want to know that their investment is being well spent. To get this reassurance they'll ask you for documentation, status reports or overview documents perhaps, not understanding that you need to take time away from your true goal of developing software and not realizing that a better request would be to see the software itself (as indicated earlier, they don't know any better). You need to recognize when your project stakeholders are looking for reassurance, something common at the beginning of a project if they don't trust your team yet, and find an alternative way to provide that assurance.
7. You're specifying work for another group. Although I have identified this situation as one where AM likely isn't appropriate it's still a common one for justifying the creation of significant amounts of documentation. Documentation is one way to communicate but it isn't the best way. Try to find alternative approaches, such as occasional meetings with the other group or use of collaborative tools, to reduce your reliance on documentation.
8. Your development contracts are routinely subject to re-competition. This problem is endemic in firms that work for government agencies, although businesses will often threaten their contractors with putting a project up for bid again if they don't perform. So what? If your primary goal is to develop software then focus on doing so and you're much more likely to perform adequately enough to keep the contract. The direct client in this situation is often operating under the misguided belief that if you don't perform they can take the documentation that you produce and provide it to the next contractor who will start from there. This borders on delusional in my opinion. If you're doing such a bad job that you lose the contract chances are very good that you've also done a bad job of the documentation and therefore the next contractor will need to rework it. Even if you've done a perfect job of the documentation, yet still lose the contract, the next contractor will very likely have people with different skills and enough time will have passed that they will need to revisit the requirements anyway. No matter how you look at it, the next contractor is very unlikely to take advantage of the documentation you produce.

4. What is the Relationship Between Documentation and Project Success?

There is no solid relationship between project success and writing comprehensive documentation, and in fact it is more likely that the more documentation that you write the greater the chance of project failure. Have you ever seen a project team write a comprehensive requirements document, get it signed off by your stakeholders, only to have the developers build something else? Or the team actually builds to spec, only to have your stakeholders say that's not really what they wanted? Or the team delivers late or over budget, even though everything looked good most of the way through the project? Have you ever seen a team create a comprehensive architecture model, have it reviewed and accepted by really smart people, only to see the architecture fail in practice anyway? Or the developers simply ignore the model and then go off and build it the way that they want to? Have you seen all this happen under the guise of management oversight, without management realizing what was happening until long after it occurred?Figure 2 is taken from my article "Examining the Big Requirements Up Front (BRUF) Approach" which explores the effectiveness of writing a detailed requirements specification early in the project life cycle. As you can see, it seems that the traditional approach to requirements appears to put your project at risk, at least where return on investment (ROI) is considered.

Figure 2: The effectiveness of a serial approach to requirements.

Why do people mistakenly think that documentation is a critical success factor in software development? My theory is that in the 1970s and 1980s many organizations moved their IT departments from a "code and fix" hacking mentality to a documentation-heavy serial waterfall process. When they did so their success rate actually improved. We even see this today with CMM/CMMI -- when you move from the code and fix CMM(I) level 1 to levels 2 or 3, you do in fact see improvements in productivity even though you've added a lot more documentation development to your process. They've "learned" that documentation improves the software development effort, and were satisfied with the answer. That's truly unfortunate.

The proponents of CMM(I), or other strategies which inevitably end up to be documentation heavy, never seem to ask the question of whether there are better ways to work. Wouldn't focusing your efforts on writing high quality software (e.g. test-driven development which in effect produces executable specifications) provide greater payback than writing documentation? Wouldn't finding ways to keep your code of high quality (e.g. refactoring) provide greater payback than writing documentation? Isn't the true value of documentation the increase understanding of the problem domain, or the solution domain in the case of architecture/design, and not the documentation itself? If so, perhaps focusing just on the modeling effort (e.g. agile model driven development) and not on writing documentation be a better strategy?

5. When Does a Model Become Permanent?

On the surface the life cycle of an agile model is fairly straightforward- Figure 3 depicts a high-level UML State machine diagram for models. Models will start out as an idea-"we need to understand how we're going to build this", "how do the users want this to work", or "we need to show what we're going to deliver"-that you either choose to model or abandon (for the sake of our discussion, any activity you choose to perform instead of modeling counts as abandonment). The model starts out being temporary, one that you intend to discard once it has fulfilled its immediate purpose, the typical fate of the vast majority of models created by agile developers. These models are typically hand-drawn sketches which discarded once the idea has been communicated to your intended audience. You'll naturally update temporary models as needed, often creating them, working on them, and then discarding them over a short period of time: many agile models are created be two or three people in a couple of minutes to facilitate their discussion whereas other agile models are created in modeling sessions of a several people over a period of several hours. The interesting transition depicted in Figure 3 is when you decide to keep a temporary model, to make it permanent, to make it one of your project team's official documents. A temporary model becomes a "keeper" when it meets all of the following criteria:

1. There is a clear and value reason to make it permanent.
2. There is audience for which the model provides value.
3. Your project stakeholders are willing to invest in having it made into documentation.

Figure 3. Life Cycle of an agile model.

Points #1 and #2 are driven by the principle Model With a Purpose: you should have a valid reason for creating the model in the first place but your documents should also have a definite purpose as well. You should know who you are creating the documentation for-perhaps a subgroup of your development team, your users, or the team(s) that will maintain and operate your system once you've released it-and what they need from that documentation. The fundamental idea is that the creation and maintenance of a document is a burden on your development team, and if you want to increase someone's burden you should be able to justify why. It's a simple as that. Documentation is a burden, and when people recognize this simple fact they put themselves in a significantly better position to consider it appropriately. Yes, effective documentation can provide significant benefits to your project team and project stakeholders, and as the principle maximize stakeholder ROI tells you the benefits should outweigh the increased burden on your team. It's important to note that sometimes the benefits are received by someone else other than the people experiencing the costs, for example your development team is impacted by the costs of creating system documentation that your maintenance developers benefit from. The implication is that when you are considering the costs and benefits of documentation you need to look at the entire picture, the trade-offs of which are described in the What Are the Issues Associated with Documentation? section. Point #3 is also driven by the principle maximize stakeholder ROI and the concept that because it is the resources of your project stakeholders that are being invested that they should be the one to direct how those resources are invested, for better or worse.

6. What Are The Issues Associated With Documentation?

Agile developers recognize that effective documentation is a balancing act, the goal being to have just enough documentation at just the right time for just the right audience. To accomplish this you must address the following issues:

1. Software development versus documentation development. This is the fundamental issue that you need to grapple with -any time spent creating documentation is time spent not developing new functionality for your users. At one end of the spectrum are projects where no documentation is written at all whereas at the other end no software is written at all, neither extreme is likely to be appropriate for your situation. Remember that your primary goal is to produce working software-you want to support your users business activities, you want to generate revenue for your organization, you want to receive feedback on your work, you want to prove to your users that you can produce – but that you need to counteract this with your secondary goal which is to enable the next effort. Therefore you're still going to need to write some documentation (user manuals, operations manuals, system overviews, ...).
2. Executable specifications offer far more value than static documentation. Executable specifications, for example a customer-test suite which specifies the majority of your requirements, or a developer test-suite which specifies the detailed design, offer significant value to developers because they not only specify your system they also help to validate it. Because these artifacts add value there is a significantly greater chance that developers will keep them up-to-date. Yes, you will still need some static documentation because tests certainly don't cover the entire range of your documentation needs, but where you can develop executable specifications you should.
3. Software developers have the knowledge, technical writers have the skill. Like it or not few technical people have good writing skills, if only for the simple reason that they haven't taken the time to gain them. The problem is that the best person suited to write documentation is the one that knows the topic being written about, in this case the developers of the system. Many teams will simply hand off a system, or portion thereof, to a technical writer and ask them to "figure it out". This has the advantage of minimizing the effort on the part of the developer but increases the effort required by the technical writer and increases the chance that they'll get it wrong. A better approach is for the developer to write the initial version of documentation and then hand it off to a technical writer for clean-up. This has the advantage that it is likely more effective, the developer does a "knowledge dump" and the technical writer refactors the material to present it effectively, but has the disadvantage that the developer may not know how to get started or even what to write about. A third approach, the best one in my opinion, is to have the technical writer and developer work together to write the documentation, learning from each other as they do so.
4. What is required during development is often different than what is required after development. You have different needs during development than you do post-development-for the sake of discussion post-development activities include the period where you a transitioning a release into production as well as when the release is in production, the Transition and Production phases of the Enterprise Unified Process. During development you're exploring both the problem and solution spaces, trying to understand what you need to build and how things work together. Post-development you want to understand what was built, why it was built that way, and how to operate it. Furthermore, during development you are much more willing to tolerate rough drafts, sketches, and greater inconsistency-it's your own work after all – whereas post-development you typically want more formal documentation. Finally, during development you likely want less documentation, you prefer to travel light, than you do during post-development.
5. Do you document as you work or when you are finished? One extreme is to write all of your documentation in parallel with developing software. The advantage is that you capture relevant information as you progress but the disadvantage is that as your software evolves, as you refactor it, you will also need to rework your documentation. Not only does this slow your development efforts down it also results in wasted effort-documentation that you wrote yesterday will need to be rewritten or discarded today, in effect with this approach you are no longer traveling light. When your requirements have not yet stabilized, when you are taking an iterative approach to development, excessive documentation can become very expensive to maintain because you are constantly updating it to reflect changes. The other extreme is to wait until you are finished and then write the documentation, the primary advantage being that you are writing about a known and stable thing (the release of the software that you just built). There are clearly several disadvantages to this approach. You have likely forgotten some of the reasons behind the decisions that you made, you may not have the right people anymore to write the documentation, you may not have funding to do the work, or the will to write the documentation may no longer exist. An effective middle ground is to capture information throughout the project as it stabilizes.
6. Can you wait until the information has stabilized? If you write documentation containing information which has not yet stabilized then you are at risk of having to rework the documentation once the information has changed. In other words, you do not want to invest much time documenting speculative ideas such as the requirements or design early in a project. Instead, wait until later in the life cycle when the information has stabilized and when you know what information is actually useful to you. The implication is that your documentation effort may be a few iterations behind your software development effort.
7. Code documentation versus external documentation. Do you place all of your documentation in your code, do you write "self-documenting" code for that matter, or do you place all of your documentation in external artifacts? Once again, you need to find an effective middle ground. When your audience is developers the best place to put the majority of the documentation is the source code. Yes, you will likely need a system overview document for this group as well but the reality is that these people aren't going to trust, let alone read, documentation outside of the code-and if they're really smart they won't trust the documentation in the code either. However, the audience for documentation is much wider than just developers. You will likely need to write documentation for people that won't have access to the source code, or at least don't have the ability to understand it, such as users, senior management, and operations staff. These audiences will require external documentation written to meet their exact needs. The AM practice Single Source Information suggests that you strive to capture information once, in the best place possible. This is often in the source code or acceptance tests. In short, strive to capture and communicate information using the best means possible.
8. Project-level versus enterprise-level documentation. Not all of the documentation that you will write will be specifically for your project team, or for the team(s) taking over your system, some of it may need to be made available at an enterprise level. You should to take advantage of existing artifacts, including but not limited to system documentation and models within your organization. This may include existing definitions of business rules, existing interfaces to legacy systems and their documentation (effectively existing contract models), a corporate meta-data repository describing the data resources throughout your company, or an enterprise business model. Where did these resources come from? The source information came from other project teams such as yours and is likely administered by a corporate team of specialists. Yes, this is clearly a situation that is likely to promote needless bureaucracy it is still possible to be agile-the centralized administration teams need to find a way to work with yours effectively. During development they should provide the resources such as existing models and meta data that you need and act as consultants when you need help understanding and working with those resources. Post development they should help you to capture relevant information to feed back into the shared enterprise resources, for example part of the process of transitioning your system into production may be to ensure that updates to your corporate business rules and meta-data repositories are made. Centralized administration teams need to be customer focused to be truly agile, they must provide real business value for their efforts, and actively strive to understand how and why the resources that they manage are used by their customers.
9. Quantity versus quality. The basic trade-off is the "security" of having the document against your trust in its accuracy. What would you rather have, 2000-page system document that is likely to have a significant number of errors in it but significant details or a 20-page, high-level overview? The large document would very likely have most of the information that you need to maintain and enhance your system, but would you trust the information contained in it? The shorter document very likely wouldn't contain the detailed information you need but it would provide a map from where you could dive into the source code, or other documents, for details. You'd be more likely to trust this document because it's shorter, worst case you could easily update or simply rewrite it if you found it to be grossly inaccurate, and because it deals with high-level concepts such as your system architecture which will change more slowly than the detailed minutiae contained in the larger document. It is important to understand that I am not saying that a larger document is automatically of lower quality than a shorter one, but I am saying that it is likely to be perceived as such until proven otherwise.
   

Traveling light requires you to think about what you are doing. At the beginning of your project ask yourself what you think you're going to need based on the nature of your project. Development of an air traffic control system will likely require greater documentation than development of a web site made from static HTML pages. As the project progresses you'll find that your initial estimate of your documentation needs changes with experience, perhaps you'll need more or less. Highsmith likes to use the analogy of hiking, he's a mountain climber - packing too light or too heavy can lead to disaster, at worst it kills you and at best forces you to turn back and rethink your strategy. Imagine crossing a desert with insufficient water, you're traveling too light, or trying to cross the same desert with a 100-pound pack strapped to your back, now you're traveling too heavy. Now imagine building a mission-critical e-commerce application without providing any documentation describing how to operate it, your project effectively fails because you've traveled too light. Now imagine building the same system with thousands of pages of documentation that you must update and validate every time you change the system, you fail again because you're traveling so heavy that you cannot respond quickly enough to changes in the marketplace. Traveling light means just enough models and documentation, too little or too much puts you at risk.

8. When is a Document Agile?

Regardless of what some people will tell you, documentation can in fact be quite effective. When is a document agile? When it meets the following criteria:

1. Agile documents maximize stakeholder ROI. The benefit provided by an agile document is greater than the investment in its creation and maintenance, and ideally the investment made in that documentation was the best option available for those resources. In other words documentation must at least provide positive value and ideally provides the best value possible. For example, if the creation of a user document provides a 50% payback on investment but providing a training course to your users provides 100% payback then you're better off choosing the training because it's a better investment.

2. Stakeholders know the TCO of the document. Stakeholders must understand the total cost of ownership (TCO) of the document and be willing to invest in the creation and maintenance of that document.

3. Agile documents are "lean and sufficient". An agile document contains just enough information to fulfill its purpose, in other words it is as simple as it can possibly be. For example, portions of an agile document could be written in point form instead of prose-you're still capturing the critical information without investing time to make it look pretty, which is in accordance to the principle Content is More Important Than Representation. Agile documents will often provide references to other sources of information, for example a contract model describing the interface to an external system could indicate that the SOAP 1.1 protocol is being used and provide a reference to the XML DTD and schema definition which define the XML documents transmitted between systems. When writing an agile document remember the principle Assume Simplicity, that the simplest documentation will be sufficient, and follow the practice Create Simple Content whenever possible.

4. Agile documents fulfill a purpose. Agile documents are cohesive, they fulfill a single defined purpose. If you do not know why you are creating the document, or if the purpose for creating the document is questionable (see earlier), then you should stop and rethink what you are doing.

5. Agile documents describe "good things to know". Agile documents capture critical information, information that is not readily obvious such as design rationale, requirements, usage procedures, or operational procedures. Agile documents do not capture obvious information. For example, documentation indicating that the F_NAME column of the CUSTOMER table captures the first name of a customer really doesn't provide a lot of value to me. Documentation indicating that the customer table does not include data for customers residing in Canada's Yukon territory because that data is stored in an ASCII flat file on another system due to regulatory reasons is likely good information to know.

6. Agile documents have a specific customer and facilitate the work efforts of that customer. System documentation is typically written for maintenance developers, providing an overview of the system's architecture and potentially summarizing critical requirements and design decisions. User documentation often includes tutorials for using a system written in language that your users understand whereas operations documentation describes how to run your system and is written in language that operations staff can understand. Different customers, different types of documents, and very likely different writing styles. You must work closely with the customer, or potential customer, for your documentation if you want to create something that will actually meet their needs. For example, I would be reticent to write the system documentation for the maintenance developers without involving some of them in the effort. Yes, sometimes you can't get these folks involved (you may have none on staff at the moment) or you may not be able to identify who within your maintenance organization will be the eventual "owners" of your system. When you don't have the customers involved you're at risk of creating too much documentation or unnecessary documentation and hence becoming less agile. You will often discover that when you involve the customers that they often have a very good idea of what they actually need, and can often provide examples of what works well for them and what doesn't.

7. Agile documents are sufficiently accurate, consistent, and detailed. Have you ever learned how to use new software by using a book describing a previous version of that software? Did you succeed? Likely. Was it a perfect situation? Likely not. Did it cover all the new features of the software? Of course not, but it still got you up and running with the software package. Were you willing to spend your own money, perhaps on the order of $30, to purchase the latest version of the book you needed? Likely not, because it wasn't worth it to you. Agile documents do not need to be perfect, they just need to be good enough.

However, having said this you need to take the advice that agile documents need to be just good enough with a grain of salt. If you are writing the operations manuals for a software system for a nuclear power plant then I highly suggest you get it right! However, few systems are truly that critical, so investing the effort required to get their documentation perfect isn't appropriate. You need to make a judgment call when it comes to writing documentation, the key issue being to identify how much ambiguity can the customers of the document accept and still be effective at their jobs.

9. What Types of Documents Should You Create?

You will need to create documentation on your project, this is true even of the most "extreme" XP projects let alone RUP projects. But what types of documentation will you potentially need to create? Table 1 lists some of the most common documents that you may decide to create as part of your development effort, documents that you will deliver as part of your overall system. Table 1 does not include management artifacts such as project schedules, software deliverables such as source code and test suites, or interim work products such as temporary models.

Table 1. Potential documents to be created by your development team.

Observation: Sometimes Un-Agility Enables Agility. Agile software development is new to many organizations and as a result there is significant fear and uncertainty concerning its viability, and although it's frustrating at times this is actually a good thing because it means that people care. Because of this fear you may be required by your project stakeholders to create extraneous documentation to help put them at ease, something that is particularly true of senior management who have likely been burned in the past by other new techniques and technologies. Often the creation of a single document, perhaps an executive overview, will give your project stakeholders enough of a "warm and fuzzy feeling" about your project to allow you to work in the manner of your choice (e.g. in an agile way).

10. Are Agilists Actually Creating Documentation and is it Any Good?

The answer to the first part of the question is a definite yes. DDJ's 2008 Modeling and Documentation survey found that agile teams were just as likely as traditional teams to write deliverable documentation such as user manuals, operations documentation, and so on. Figure 4 summarizes the results of the survey pertaining to deliverable documentation. The important thing is that this survey should help to lay waste to some of the misunderstandings that people have when it comes to agile software development and documentation.

Figure 4. Deliverable documentation creation.

The answer to the second part of the question is maybe. In DDJ's September 2009 State of the IT Union we explored the quality of the deliverable documentation being produced by development teams following various paradigms, the results of which are shown in Figure 5. As you can see the reported quality of the documentation produced by agile teams is at the same level as that of traditional teams, although iterative teams appear to be slightly more effective than both. The interesting aspect of Figure 5 is that all development paradigms were found wanting when it came to documentation quality (they all had negative scores, hence all the bars on the histogram face left).

Figure 5. Quality of "deliverable documentation".

11. When Should You Create Documentation?

Let's begin with some fundamental advice (described in detail elsewhere in this article):

• Prefer executable specifications over static specifications (documents)
• Single source information
• Document stable concepts, not speculative concepts, and thereby document as late as possible in the life cycle
• Documentation is the least effective means of communication

Now let's consider when in the software development life cycle (SDLC) it makes sense to write documentation. Figure 6 depicts the typical strategies towards documentation for both traditional and Agile development, the curves representing the total amount of effort invested to date in writing documentation. In this case documentation includes interim work products such as project plans and specifications that you may not decide to retain at the end of the project (some teams do, some don't). The diagram also indicates the type of documents that might be created at given points of time, although this list is not meant to be exhaustive. Figure 6 in effect depicts the strategy of the document late best practice.

Figure 6. Documentation through the SDLC - Document Late Strategy.

Another, more disciplined approach, is to document continuously such as support, operations, system overview, and user docs as you go. This strategy is overviewed in Figure 7. The idea is that if a system is to be potentially shippable at the end of each iteration then that includes the deliverable documentation as well. The challenge is that any documentation that you write needs to be evolved over time in sync with your code which can be painful (see the next section). If you adopt this strategy then there are three heuristics to consider:

1. For long iterations, four or more weeks, write the documentation in the iteration that the corresponding functionality was developed in.
2. For short iterations, two weeks or less, consider writing the documentation the following iteration (although strive to write it that iteration).
3. No matter what the iteration length, you'll want to experiment with both approaches to find out what works best for you. In the end the two strategies typically end up being little different because with a long iteration you'll tend to leave writing the documentation to the end of the iteration anyway.

Figure 7. Documentation through the SDLC - Document Continuously Strategy.

With a document continuously approach many teams will include criteria around updating deliverable documentation in their definition of done for the iteration.

12. When Should You Update Documentation?

In this respect documents are just like models, my recommendation is to follow the practice Update Only When It Hurts. Agile documents, like agile models, are just good enough. Many times a document can be out of date and it doesn't matter very much.For example, when I wrote the first version of this article I was working with the early release of the JDK v1.3.1 yet I regularly used reference manuals for JDK 1.2.x-it's not a perfect situation but I get by without too much grief because the manuals I'm using are still good enough.Would the manuals for Java v1.0.x be sufficient? Likely not, because there has been a significant change since that release and my productivity loss would be much greater than the cost of new manuals.

In addition to the fundamental requirement of your project stakeholders authorizing the investment of resources required to do the work, you should use the follow heuristics for deciding when to update documentation:

• Update contract models and re-release them ideally before, and minimally in parallel to, releasing the item(s) that the model describes.
• Documentation that is intended as part of the system, such as operations and user manuals, should be updated and released before or with the system itself.
• The customer of the documentation is being inordinately harmed, including a significant loss of productivity, because the documentation is not updated (e.g. it hurts).

Yes, it can be frustrating having models and documents that aren't completely accurate or that aren't perfectly consistent with one another. This frustration is offset by the productivity increase inherent in traveling light, in not needing to continually keep documentation and models up to date and consistent with one another. Do you want to write software or write documentation?

13. Effective Documentation Handoffs

A documentation handoff occurs when one group or person provides documentation to another group or person. Agile developers desperately try to avoid documentation handoffs because they are not a very good way for people to communicate. Unfortunately documentation hand-offs are a reality in some situations -often your development team is so large it cannot be co-located, perhaps a subsystem is being created by another company (implying the need for a contract model), perhaps important project stakeholders are not readily available to your team, perhaps regulations within your industry or organization require the production of certain documents, or perhaps your team is made up of specialists instead of generalizing specialists. The following strategies can help to increase the effectiveness of documentation handoffs:

1. Avoid documentation handoffs. As you migrate to an agile software development process you will constantly run into people who are not as agile, people who see nothing wrong with documentation handoffs. Point out that there are better ways to communicate-face-to-face conversations, video conferencing, telephone conferencing-that you should consider before writing documentation, and whenever possible try to find a better way that fulfills your needs.
2. Support handoffs with other means of communication. If you can't avoid providing documentation to someone else you should at least strive to support the handoff with face-to-face communication or other approaches. This may enable you to write less documentation, therefore allowing you to focus on other activities, and will help you to avoid some of the common disadvantages of documentation such as misunderstanding the material.
3. Avoid documentation handoffs. Chances are good that the people you are interacting with don't like writing and receiving documentation either-at least it doesn't hurt to ask.
4. Write agile documentation. See the section Strategies for Increasing the Agility of Documentation.
5. Avoid documentation handoffs. I can't stress this enough.

14. Can Templates Help?

Yes and no. My experience is that simple templates which focus on capturing the minimal, critical information that you require in a document can be very useful. Sadly, many templates are the exact opposite of this and try to capture all of the information that you might need for any situation. These templates prove to be ineffective for several reasons:

1. The template is time consuming and expensive to create. The creation of a comprehensive template takes significant effort.
2. People will actually fill them out. A comprehensive template will contain fields which aren't applicable for a given project. Some people will see the field and attempt to fill it in anyway, wasting their time and reducing the value of the document because it now contains needless information that may confuse users of it later. Others will choose to indicate that the field isn't required, something which also takes time.
3. Reviews take longer. There's now more information in the documents to review, some if it may be the needless information mentioned above. The review will often slow down when it hits a field that is indicated that it isn't required because people will often question that decision.
4. Total cost of ownership (TCO) increases. The more documentation you write the heavier you're traveling, slowing you down and increasing your overall TCO for that documentation.

15. How Can You Reduce Documentation Cruft?

"Cruft" is a slang term which refers to areas of something which are badly designed, poorly implemented, or redundant. It is important to note that cruft is based in part on the perception that someone has of an artifact in addition to the actual quality of that artifact. With respect to documentation, cruft occurs when out of date, redundant, out-of-scope, or poorly written information is included. Table 2 overviews strategies for reducing the cruft in your documentation. The CRUFT rating of the document, with 100% being a bad thing, is calculated with the following formula: 100% - C * R * U * F * T, where the following factors are measured as percentages:

• C = The percentage of the document that is currently "correct".
• R = The chance that the document will be read by the intended audience.
• U = The percentage of the document that is actually understood by the intended audience.
• F = The chance that the material contained in document will be followed.
• T = The chance that the document will be trusted.

Table 2: Strategies for reducing documentation cruft.

16. When is Documentation the Best Option?

Rarely. Let's consider the situations when you would consider writing documentation:

1. To communicate information during development. Traditional software development theory calls out for the creation of detailed documentation throughout the software development life cycle. Although this sounds like a good strategy in theory, in practice it proves to increase your overall costs and project risk. The reason why is that documentation is actually a very poor way to communicate, as Figure 8 depicts. The implication of this diagram is that you should choose the best communication option available to you given your current situation. Documentation options, in particular "paper specifications" are your least desirable choice, not the most desirable one.
2. To specify something. Agilists have shown that by taking a Test-Driven Development (TDD) approach you are effectively creating detailed, executable specifications on a Just-In-Time (JIT) basis. To scale TDD we're taking an Agile Model Driven Development (AMDD) approach to address the high-level issues which can't easily be captured in the form of tests. So, some high-level specifications may make sense to support your other communication efforts.
3. To permanently record information. This is where documentation starts to make sense. You'll still want to capture the information in the best way possible for your audience, for example maintenance programmers would very obviously prefer high-quality source code, a full test suite, and a bit of overview documentation over highly-detailed system documentation. You'll still need to write support documentation, operations documentation, and user documentation, but a lot of the technical documentation written by traditional teams rarely seems to be effective in practice.
4. To conform to regulations. Like it or not, we live in a regulatory world. Industry regulations such as Sarbanes-Oxley and the Food and Drug Administration (FDA) Guidelines will often motivate people to write more documentation than they normally would have, and often this is a good thing. However, having read several of these regulatory guidelines I have yet to see one that says to write mounds of useless documentation or to be incredibly wasteful with your money. Yet, in practice many organizations choose to do exactly that. My advice is to read the regulations and then find effective ways to fulfill the requirements. If you let the bureaucrats among us interpret the regulations don't be surprised when you end up with a bureaucratic approach.

Figure 8. Comparing the effectiveness of various communication modes.

17. Best Practices for Increasing the Agility of Documentation

If you can't avoid writing a document, how can you at least write it in an agile manner? The following best practices should help:

1. Prefer executable specifications over static documents
2. Document stable concepts, not speculative ideas
3. Generate system documentation
4. Keep documentation just simple enough, but not too simple
5. Write the fewest documents with least overlap
6. Put the information in the most appropriate place
7. Display information publicly
8. Document with a purpose
9. Focus on the needs of the actual customers(s) of the document
10. The customer determines sufficiency
11. Iterate, iterate, iterate
12. Find better ways to communicate
13. Start with models you actually keep current
14. Update only when it hurts
15. Treat documentation like a requirement
16. Require people to justify documentation requests
17. Recognize that you need some documentation
18. Get someone with writing experience

17. Translations

• Spanish