Agile/Lean Documentation: Strategies for Agile Software Development

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

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.

Agile Modeling

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.

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

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.

Agile Documentation

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.

Agile Model Lifecycle


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.

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.

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.

Document stable things,
not speculative things.


7. 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 project, or even no documentation, perhaps on a very small project. But for the vast majority of projects 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.

As another example, the RUP suggests that you create a Software Architecture Description (SAD) document to define your architecture. Yes, 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 project? 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 project as one of our deliverables to the maintenance team but we certainly didn't need it during development and it clearly did the project team more harm than it did good.

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.

Potential Document

Audience

Description

Advice

Valuable Deliverable?

Contract models

Other Teams

A document describing the technical interface to a system or portion of a system.

Yes

Design decisions

Developers, Maintenance Developers, Project Managers

A summary of critical decisions pertaining to design and architecture that the team made throughout development

  • Question the need for most of this information. Are people really going to care several years from now why you did something?

  • Focus on decisions that are not obvious, which had other reasonable alternatives, or ones where you explored what initially looked like a reasonable alternative that in the end proved insufficient for your needs.

  • The goal of this effort is to avoid needless refactoring at some point in the future or rehashing a previously made decision.

  • Design decisions are often documented throughout other artifacts, such as system overviews and source code, although you may choose to have a separate document when appropriate to the situation.

Perhaps

Executive Overview/Vision Statement

Senior Management, User Management, Project Management

A definition of the vision for the system and a summary of the current cost estimates, predicted benefits, risks, staffing estimates, and scheduled milestones.

Advanced: Consider including listing of major stakeholder groups, their representatives (if any), and their primary goals.

  • This document is typically used to gain funding and support for your project as well as provide status updates to important project stakeholders who may not be actively involved with your project on a day-to-day basis.

  • Keep it short, ideally a few pages, and consider writing it in point form.

  • Have the courage to make this publicly available to everyone that should have access to it, even when it contains bad news, according to the principle Open and Honest Communication.

Valuable interim document

Operations documentation

Operations Staff

This documentation typically includes an indication of the dependencies that your system is involved with; the nature of its interaction with other systems, databases, and files; references to backup procedures; a list of contact points for your system and how to reach them; a summary of the availability/reliability requirements for your system; an indication of the expected load profile of your system; and troubleshooting guidelines.

  • Your operations department often has a standard format for this type of documentation or at least may have good examples from other systems that they can provide you to base your document(s) on.

Yes

Project overview

Developers, Managers, Maintenance Developers, Operations Staff

A summary of critical information such as the vision for the system, primary user contacts, technologies and tools used to build the system, and the critical operating processes (some applicable to development, such as how to build the system and some applicable to production, such as how to back up data storage). Also provides references to critical project artifacts such as the source code (the project name in the source code control system is often sufficient), where the permanent models pertaining to the system (if any) are, and where other documents (if any) are.

  • I typically create and maintain this document during development.
  • Keep it short and to the point, I don't ever remember one getting beyond ten printed pages and most are less than five.

  • This document serves as a starting point for anyone new to the team, including maintenance developers, because it answers fundamental questions that they are likely to have.
  • Whenever you first share this document with anyone ask them to keep track of major issues that they were not able to easily resolve using this document, or any misinformation they discover, to provide insight into potential updates for the document.
  • I often call this a "Good Things to Know" document.
Yes

Requirements document

Developers, Maintenance Developers,Users, User Managers

This document defines what the system does, summarizing or composed of requirements artifacts such as business rule definitions, use cases, user stories, or essential user interface prototypes (to name a few).

  • Writing a requirements specification early in the life cycle should be seen as a very large risk.

  • XP projects typically favor inclusive requirements techniques such as user stories and CRC cards.

  • RUP projects tend towards more formal requirements artifacts and documentation.

  • Disciplined agile teams capture the majority of their requirements as executable specifications. As a result these teams only need brief overviews of the scope which would be part of the system documentation.

In scaling situations, particularly when regulatory compliance, large teams, or geographically distributed teams are an issue

Support documentation

Support Staff

This documentation includes training materials specific to support staff; all user documentation to use as reference when solving problems; a trouble-shooting guide; escalation procedures for handling difficult problems; and a list of contact points within the maintenance team.

  • You will find that your support department often has a standard escalation procedure in place, therefore you will not need to write one, and like the operations department may have standard templates or examples that you can work from.

Yes

System documentation

Maintenance Developers, Developers

The purpose of this document is to provide an overview of the system and to help people understand the system.Common information in this document includes an overview of the technical architecture, the business architecture, and the high-level requirements for the system. Detailed architecture and design models, or references to them, may also be included where appropriate.

  • System documentation helps to reduce perceived risk on the project by providing "truck insurance", the assurance that if the development team leaves, or gets hit by a truck[1], that critical information about the project is left behind. Unfortunately this is typically false insurance-if you lose someone(s) then no matter how good the documentation is you have a serious problem on your hands because new people still need to be identified, assigned to your system, and need to learn the system. You're much better off increasing your project's "truck number", the minimum number of people that if you lost them would put your project at risk, by supporting knowledge sharing practices such as Active Stakeholder Participation, Collective Ownership, and Model With Others.

Yes

User documentation

Users, User Managers

Your users may require a reference manual, a usage guide, a support guide, and even training materials. It's important that you distinguish between these different types of documents because the way that each one is used varies: one is for quick lookups, one is for discovering about how to work with the system, one is for how to obtain additional help, and one is for training.

.I typically base my usage guide and training materials on the use cases for the system -the use cases describe how the actors work with the system, therefore they should be a very good foundation on which to base both of these documents.

.User documentation should be considered part of the user interface for your system and therefore should undergo usability testing.

Yes

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.

Chance that a team will create deliverable documentation


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

Quality of deliverable documentation



11. When Should You Create Documentation?

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

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.

Agile Documentation - 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.

Agile Documentation - 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.

Factor Improvement Strategy
C = How correct is the document?
  • Minimize the information contained in the document
  • Single source information by capturing it in one place only
  • Have more than one person work on the document together (i.e. pair write the document and thereby do inspections in progress)
  • Have shared ownership of all documentation so that multiple people will work on it
  • Document stable, not speculative concepts
R = Will the document be read?
U = Will the document be understood?
  • Take an evolutionary (iterative and incremental) approach to its development so that you gain feedback as to its actual value
F = Will the document be followed?
  • Prefer executable specifications, such as customer tests and developer tests, over static specifications such as traditional requirements and design documents. By doing so the specification actually provides value to the audience
  • Capture high-level information in documentation, not details. When you specify details of how to do something and then hand the document to someone for them to follow, you effectively take all of the joy out of the activity for that person because you've done the thinking for them. What would the motivation be for an intellectual worker, such as an IT professional, to follow detailed instructions?
T = Will the document be trusted?
  • Work closely with the audience of the document
  • Take an evolutionary approach

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.

Comparing 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