Lean/Agile Documentation: Strategies for Agile Teams

1. Critical points
2. Models, documents, and source code
3. When is a document agile?
4. Why do people create agile documentation?
5. What is the relationship between agile documentation and team success?
6. When does a model become permanent?
7. What are the issues associated with agile documentation?
8. Traveling light? What does that mean?
9. What type of documents do you need?
10. When should you create agile documentation?
11. When should you update agile documentation?
12. Effective hand-offs
13. Can templates help?
14. How do you calculate the value of an agile document?
15. How can you improve agile documentation quality?
16. When is documentation the best option?
17. Effectice practices for agile 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 an initiative.
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 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 lifecycle.
22. Update documentation only when it hurts.

2. Models, Documents, and Source Code

Let’s start with understanding the relationships between models, documents, source code, and documentation, something depicted in Figure 1. From AM’s point of view a document is any artifact external to source code whose purpose is to convey information in a persistent manner. This is different from the concept of a model, which is an abstraction that describes one or more aspects of a problem or a potential solution addressing a problem. Some models will become documents, or be included as a part of them, although many more will simply be discarded once they have fulfilled their purpose. Some models will be used to drive the development of source code, although some models may simply be used to drive the development of other models. Source code is a sequence of instructions, including the comments describing those instructions, for a computer system. Although source code is clearly an abstraction, albeit a detailed one, within the scope of AM it will not be considered a model because I want to distinguish between the two concepts. Furthermore, for the sake of discussion the term documentation includes both documents and comments in source code.

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

3. 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. They 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.

4. Why Do People Write Agile Documentation?

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 stakeholders require it. The creation of documentation is fundamentally a business decision, you are investing the resources of your 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 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 stakeholders ask you to? Preposterous you say! Well, my experience is that this isn’t preposterous. Your 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 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 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.

Your stakeholders must understand the total cost of ownership (TCO) for a document, and your stakeholders must explicitly decide to invest in that document.

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 initiative’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 team and can do so in a productive manner.
2. The requester mistakenly thinks that documentation has something to do with 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 initiative, 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 stakeholders are investing significant resources in your 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 stakeholders are looking for reassurance, something common at the beginning of an initiative 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 an initiative 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.

I don’t believe in Santa Claus, nor do I believe that programmers will keep external documentation up to date. Four decades of experience have shown that this particular dogma is fantasy at best.

5. What is the Relationship Between Agile Documentation and Team Success?

There is no solid relationship between success and writing comprehensive documentation, and in fact it is more likely that the more documentation that you write the greater the chance of failure. Have you ever seen a 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 initiative? 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” that explores the effectiveness of writing a detailed requirements specification early in the lifecycle. As you can see, it seems that the traditional approach to requirements appears to put your initiative 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?

6. When Does a Model Become Permanent?

On the surface the lifecycle 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 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 stakeholders are willing to invest in having it made into documentation.

Figure 3. Lifecycle 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 team and 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 stakeholders that are being invested that they should be the one to direct how those resources are invested, for better or worse.

As you can see in Figure 3 you can rethink your decision about making a model permanent, often because you realize that the benefit provided by the model is far less than the burden of maintaining it. When this happens the model is either discarded outright or more commonly the owners of that model simply stop keeping it up to date and it starts to “gather dust”. Sometimes these models are revived months or years later by the development team, the maintenance team, or the “redevelopment team” if the system is being rewritten. These stagnant models are often reviewed, recognized as being significantly out of date, and either then discarded or used as a template from which to create a new version of the model. Ideally this new version is leaner than the original model, because if the original model didn’t provide positive value to your effort then an updated version of it following the same approach likely won’t provide value either. Techniques for doing so are discussed in the Section Strategies for Increasing The Agility of Documentation.

7. What Are The Issues Associated With Agile 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 initiatives 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. 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 initiative 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 an initiative. Instead, wait until later in the lifecycle 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. Team-level versus enterprise-level documentation. Not all of the documentation that you will write will be specifically for your 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 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.

Important point: Document stable things, not speculative things.

8. What Does it Mean to “Travel Light”?

One of the greatest misunderstandings people have about the concept of traveling light is that it means you don’t create any documentation. The reality is that nothing could be further from the truth. What traveling light does mean, at least in the context of AM, is that you create just enough models and just enough documentation to get by. On extremely rare occasions that may mean you create no models whatsoever, perhaps on a very small team, or even no documentation, perhaps on a very small team. But for the vast majority of initiatives you need to create some models and some documents.

How can you ensure that you’re traveling light? A good rule of thumb is that you shouldn’t create a model or document until you actually need it – creating either thing too early puts you at risk of wasting your time working on something you don’t actually need yet. I once worked on a commercial software system, one that organizations could either buy and install out of the box or more typically would purchase and then have the company that I worked for modify it to meet their exact needs. One day our sales person got a new lead on a company that wanted our system, but this company was in a new domain that we didn’t have experience in yet. We figured we were going to get this sale, we eventually did in fact get it, so before we even met with the client myself and a couple of others started modeling the expected changes that we thought we would need to make. After several days of modeling sessions we came to the conclusion that the changes were going to be easy, our system was amazing after all, and we would have no problem supporting this new client. Then we talked to them. Of the seventy or so new requirements we had identified we had gotten about half of them right, not bad considering we didn’t know what we were talking about, but we had missed several hundred others. Naturally our models based on our faulty requirements were of little value and we had to discard them and start fresh, something that was made a little harder because we needed to shift our mindset away from our original approach. Even worse, we went into the first meeting with a cocky attitude because we thought we knew it all, an attitude that would have lost us the customer if it wasn’t for the fancy maneuvering of our sales person. The bottom line is that we didn’t need the model at the time we created it, instead we should have waited to create the model after talking to our client and after securing the sale.

Defining your system’s architecture is very good thing to do, as I discuss in Agile Architecture, but do you need to create a document early in the initiative. Sometimes yes, sometimes no. A couple of years ago I worked on a mission-critical system where we developed our architecture model on a plain old whiteboard (POW), we were following the practice Display Models Publicly, as a collection of free-form diagrams. Because the process told us to create a SAD we did so, even though most of the developers were working from the whiteboard sketches. Because the RUP product provides a pretty good Microsoft Word template for a SAD we used it as the basis from which to work. A few of the developers printed out diagrams from the SAD document, we had transcribed our sketches into Microsoft Visio, to tack to their cubicle walls because they couldn’t easily see the diagrams from where they sat. Every time the whiteboard sketches changed sufficiently we would have to update the electronic versions of the diagrams plus corresponding sections in the SAD document. The advantage of having the SAD document was that it provided a description of what we were building, a document that we distributed to management and made available to anyone within the organization that was interested. The disadvantage, from what I could tell, was that nobody was using the SAD document effectively. I’m not sure the managers ever looked at it, and if they did it was a cursory inspection at best because we never received any feedback from them. The developers that needed copies of the diagrams could just as easily taken a digital snapshot of the sketches and either created a shared architecture web page or just printed those out.This would have also been a SAD document, albeit in a different form, according to the principle Content is More Important Than Representation because it still would have described our architecture (which is the fundamental purpose of a SAD document).By the same reasoning our whiteboard sketches were also a SAD document, although one that wasn’t permanent and one that fixed in a permanent location. In my opinion we had made three fundamental mistakes and thus were traveling heavier than we needed to: we chose the wrong format for the documentation, we documented too early, and we created too much documentation. The added overhead of maintaining the SAD as a Word document slowed us down because we effectively had that information in several locations-the whiteboard which is what we were working from, the Word document which was almost superfluous, and in our code itself. Furthermore, we could have been developing software instead of documentation, and worse yet the update effort took up a large portion of the time of one of our senior developers so he couldn’t help to mentor and coach the junior developers. Granted, it was useful to have this document at the end of the initiative as one of our deliverables to the maintenance team but we certainly didn’t need it during development and it clearly did the team more harm than it did good.

Traveling light requires you to think about what you are doing. At the beginning of your initiative ask yourself what you think you’re going to need based on its nature. 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 initiative 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 team 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.

9. What Types of Documents Should You Create?

You will need to create documentation, this is true even of the most “extreme” XP or Scrum teams. 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. It does not include management artifacts such as 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 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 stakeholders enough of a “warm and fuzzy feeling” about your initiative to allow you to work in the manner of your choice (e.g. in an agile way).

10. When Should You Create Agile 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 lifecycle
• Documentation is the least effective means of communication

Now let’s consider when in the software development lifecycle (SDLC) it makes sense to write documentation. Figure 4 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 plans and specifications that you may not decide to retain at the end of the initiative (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 4. 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 5. 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 5. 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.

11. When Should You Update Agile 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 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?

12. 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 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.

13. 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 initiative. 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.

14. How Can You Calculate the Value of a Document?

To calculate the value of a document, apply the CRUFT formula of Figure 6.

Figure 6. The formula to calculate the potential value of an artifact.

15. How Can You Improve the Quality of Agile Documentation?

The formula to calculate the value of a document used five qualitative quality concerns. In Table 2 I overview how to address each of those concerns.Table 2: Strategies for improving documentation quality.

16. When is Agile 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 lifecycle. Although this sounds like a good strategy in theory, in practice it proves to increase your overall costs and risk. The reason why is that documentation is actually a very poor way to communicate, as Figure 7 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 7. Comparing the effectiveness of various communication modes.

17. Effective Practices for Agile Documentation

If you can’t avoid writing a document, how can you at least write it in an agile manner? The following core 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.

18. Translations

• Spanish