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.