Documentation Debt in Scrum

Recently one of my Scrum Masters came to me with a question. He said, “We have been going crazy building things since we switched to Scrum a few months ago. We have made some major changes to our system architecture and design, but we haven’t documented them. That is starting to scare me. What should we do?”
It was a great question and I was pleased to hear it because it showed me a thinking Scrum Master.

Dealing with documentation is often confusing for new Scrum teams. Many teams overdo the rejection of project documentation when they start to become Agile. Tribal knowledge can appear to be all you need on a tightly knit team, especially one that is also embracing emergent architecture and design.
Another reason teams stay away from documentation is that they think that “there is a rule” against documentation in scrum. I’m reminded of the developer who, in response to a very pointed accusation of technical negligence during a post-mortem at a famous internet company said, “Well, we wanted to do a better design, but we were doing scrum so we weren’t allowed to.” Yes, it is as lame as it sounds, and it’s not true. The scrum framework doesn’t prevent or prohibit anything, it merely challenges you to do the right amount of the right things for the right reasons while you are developing.

Tribal knowledge has its limitations. While it is healthy and productive to Just Say No to the kind of rote documentation requirements that burden many teams, it’s also true that there can be a lot to remember about how a system works and it’s not a sin to use documentation to improve the ability of a team to work to the best of its abilities.

The key to deciding when and how much is the nearly banal idea that Scrum gives you many options in almost everything you do, documentation being no exception. Scrum does not forbid documentation. It simply says “create the right amount, at the right time.” The cool part is you can do that in Scrum, which leads to the best documentation possible. But beware. You need to think through your needs. Check out the following cautionary tale:

My first Scrum team decided that they wanted to do the best job ever on their technical documentation. The team wrote quite a few designs during the first few sprints of our 18 month project, but soon they settled into a comfortable routine where the need for a design or other document was recognized by all when a new story was activated. We started to accumulate dozens of small, story-sized design documents on a wiki page designed for easy browsability. So far so good.
Then, the inevitable happened and a new guy joined the team. As the team’s manager and Scrum Master (yeah, yeah, I know, but that’s not what this post is about) I was bursting with pride as I familiarized him with our documentation wiki and its over 100 design documents.

“Just go have a read and let us know when you’re ready to dive in,” I said, expecting to see him in a week or so. Next day, new guy shows up with a glazed look and says, “Could I just get a bug to fix, please?”
Moral of the story: Even really great, up to date, accurate, and correct documentation is not a silver bullet.

Remembering this story makes me smile whenever people bring up this topic in CSM classes, because the “new person joining the team” scenario is the favorite example that people use to demonstrate the crushing need to have extensive technical documentation.

Scrum allows you to write documentation contemporaneously (I hate to brag, but I spelled that correctly on the first try!) with design and coding, and it is easy to make your documentation correct. The Definition of Done gives you a mechanism that can nearly guarantee that technical documentation can be kept up to date as the system changes over time.

Think about your documentation requirements by thinking of the problem you are trying to solve. Do you only need design documentation? Are you required to provide documentation for compliance with standards or laws like SOX? Will the documentation be for communication with other teams within your company? Will it be input to a separate department that produces extensive user manuals? Each of these needs drives different approaches to documentation. Agile teams are expected to make conscious decisions about what they do and why they do it, and documentation is no exception.

Oh…so what happened with my Scrum Master and his team and their documentation debt? I don’t really know. Not my job. It’s up to them, isn’t it? If you really want, I’ll send him an email and ask him.


9 thoughts on “Documentation Debt in Scrum

  1. Kudos for writing about the need for documentation; I think there is too much fear of documentation and reliance on in person ad hoc communication in scrum.

    However I think getting back to the engineer who said regarding architecture, “we were doing scrum so we weren’t allowed too”…I think is a valid comment.

    If the iterations are too short, and too much emphasis is put on “delivering value” on each sprint, then there won’t be enough time to really do a good architecture.

    Pretend you’re setting up a streaming service ala netflix and you deliver value every 1 or 2. When will the backend architecture really good done to handle the traffic? Never most likely.

    So I think people need to look beyond scrum entirely and look at what they are trying to accomplish and go from there.


    1. Hi Jordan,

      Those are indeed concerns, and there are any number of ways to address those concerns in scrum. Smaller stories and better designed stories are a big part of it. One of the great things about splitting stories is that we can decide how much value to deliver at one time, so if it will be more difficult to do a good job then we just deliver less within each sprint so we have the time to build things right.

      My own experience with environments like the netflix example you give is that there is value in having some system architecture and there is also value in completing the details of architecture and design as the stories get implemented. Doing both leads to a very good place, where design and implementation inform one another. Try it.


      1. Hi Alan

        Have you done any architecture for high volume streaming services? Just curious — I have.

        You mention some experience in that area.

        I don’t think you can make user stories I’m talking about small enough to split up into sprints, that are meaningful anyway… (As I user..I want to watch anything, anytime, anyhere)…Splitting that up to “I’ll settle for watching the simpsons on one device” is banal and not representative compared to the overall goal.

        Although I think you are alluding to “architectural sprints” — and I think that is a good idea, I don’t need to “try it” with scrum because

        1) Most scrum people are too blinded by dogma to be flexible in that area (dialing in the amount of value, sprint length, documentation required, architecture required etc)

        2) Scrum starts out as a broken process (tribal, adhoc, short termist, with many closed minded adherents

        3) I use a “more agile” traditional business process to start with, and hence, I don’t need to use scrum.

        There is no need for me to try to start with scrum as a foundation, when there are other foundations which are more apropos, and they are easier to tweak to taste without being saddled by the aforementioned burdens.


      2. OTOH if you mean try doing some architecture while at the same time doing a representative test case of that architecture (a real user story) I would agree with that and I do that all the time and have for several decades…


  2. Probably the main problem with Scrum is that it’s not documented properly itself, and that’s why teams get confused on whether to document or not. Traditional project management, on the other hand, is well documented by the PMBOK.

    1. Hi PMHut,

      I’d have to say that Scrum’s flexibility, coupled with the idea of continuous learning, is one of its strong points and as far as I can determine the success rates, quality output, and productivity of scrum teams bears me out. The PMBOK is, in my opinion, overly prescriptive and substitutes direction for understanding. Getting a team to examine its process and its domain so that constant improvement can be made leads to far more powerful solutions.

      At least, in my opinion.


  3. There are incentives for the development team NOT to document:

    – Get more work done (Documentation is always considered to be counter productive to individuals)
    – Job security (Yes, I mean it.)
    – Maintenance headache (Change, change…)

    People are lazy. “Right amount at the right time” often means “None, not at all”. You cannot let the “Team” have discretion on documentation if you need some. This is the responsibility of the management (outside of the SCRUM team) to make sure what you need and have your needs visible as stories.

    1. Hi Robin,

      If everybody is lazy and the team can’t be trusted to create the documentation that is needed, then how can they be trusted to build quality software at all? I’m afraid that if you feel strongly about this, then you have more or less chosen not to be Agile because you don’t believe in even the possibility of it working. I know, because I have seen it many times, that not all people are lazy and most teams want to be professional and do well, and you can trust a team to do all of the things it should in order to produce professional quality product. That’s not to say that a manager can’t add value by providing a good conscience or hold up a high quality and professionalism bar or coach and mentor the team, but overall my experience is that teams will do the right thing in most cases, once they know how and once they believe that is what is desired by customers and stakeholders.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s