One of the major selling points of Scrum to developers is how much less documentation is involved. Developers worked hard to get where they are: a college degree, nights and weekends at home working through books and exercises trying to learn the latest language, and struggling through their first few projects to get something that works into production. They don’t want to come all that way just to spend most of their day in the word processor. They want to code.
Author: Nate McKie, CTO, Asynchrony Inc., www.asynchrony.com
When Scrum gives them a taste of what it means to emphasize code over specifications and architectural diagrams, they never want to go back. However, completely giving up on documentation has its own price, and it’s one that can be avoided without a lot of effort.
Agile even de-emphasized documentation in the Manifesto for Agile Software Development: Working software over comprehensive documentation.
So is all documentation bad? I think you know the answer.
There are many times in the life of a project when a little documentation goes a long way, and development teams should consider that it’s worth taking a bit of time away from coding to write things down.
Here are some examples:
Remembering Why You Made Decisions
If a project goes on much longer than a few months, there will be times when decisions are made that change the course of the development effort. It may be a decision to use (or explicitly avoid) a particular tool, framework, or platform. It may be a decision to write tests a certain way, or not write them at all for some cases. It may be a decision to throw away all the practices you would normally engage in and do things in a completely different way. These decisions will happen, and they tend to last.
Someday, long after these decisions were made, someone on the team (usually a new addition, they’re so annoying, aren’t they?) will ask “Why are we doing this?” What answer will they receive?
If one or more people on the team with good memories have been with the project for a while, maybe they’ll get the actual reason. But in most cases, I’m afraid the answer will be, “Because we’ve always done it that way.” That is not an answer anyone really wants to hear.
Now you have a choice. You can keep doing things the way you’ve been doing them, because you’re used to the pain, and it’s safer, since you don’t remember why you started doing them that way. Alternatively, you can make a change and hope that you’ve considered all the possible repercussions. What could go wrong? Well, as it turns out….plenty.
You could go down a path that has already been explored and rejected, wasting precious project time and effort.
You could frustrate your customer by making a change that is in conflict with the way the business needs the system to work.
You could violate a compliance issue that was being mitigated by the way you were doing it, and get yourself and/or your customer in legal trouble.
All of these consequences could have been avoided by just taking the time to write things down. When your team makes a decision that changes the way you work, write down the date you made the decision and the logic behind it (if you’re good, you even had a process for making the decision that would have artifacts you can point to). Then, when someone asks the question later, you can answer with confidence when a new team member asks why you’re doing things that way or using that tool.
Preparing for Automating an Annoying Process
Developers frequently find processes they want to automate. These are the ones that they repeat regularly and waste precious development time. However, too often I’ve seen cases where there is a manual process that is only needed once in a while (maybe every few weeks), and involves a series of steps that must be followed in a specific order. If no one has bothered to write this process down, many times it can be followed incorrectly or steps can be missed, and even more time is wasted. Furthermore, there’s no practical way to automate those processes without writing them down first.
If you find yourself performing a task with multiple steps that there is any chance of doing again, write the steps down. This will save time when the next person has to perform the process, and will prepare you for the day when you finally get so frustrated that you automate it.
Covering Your Posterior
On Agile projects, as the manifesto describes, we value face-to-face communication. This kind of communication about requirements is the most optimal, as all of the information can be gathered, both verbal and non-verbal. However, there are times when even these words can be misinterpreted, or more likely, misremembered. This can happen on either side: the developer could think they heard something that the customer didn’t say, or the customer could forget (I’m going to assume this mainly happens unintentionally) that he or she told the developer to go in a particular direction. This can result in the developer later having to insist that they were told to take some action, with no way to back up whether or not this is true. In this case, my experience is that the customer almost always wins, and the developer walks away feeling frustrated and possibly abused.
That doesn’t sound like what developers really want to happen. Let’s see, how could we avoid this situation? I don’t know…maybe we could try writing things down? All it would take is a follow-up email after that phone call or face-to-face meeting that describes in the developer’s words what they think they were told to do. This doesn’t require much effort, and it gives a great audit trail later when the question comes about why the system was developed the way that it was.
Ideas for Easy Documentation
Documentation is unnatural for most people, and downright painful for most developers. Yet, as illustrated above, it has value. Here are some ideas for making it less like sharp-stick-eye-poking:
Do it right away. Many of us like to procrastinate when it comes to the stuff we don’t like to do. Don’t do it with this kind of documentation. It’s best when it’s fresh, and it comes easier when you don’t have to stop and remember. As soon as you have the conversation, find a workstation or a mobile device and write down the summary.
Find good tools to help. Speaking of mobile devices, there are just so many great tools out there now for writing these things down. Back in the day, we had to go find the right place on a wiki and use some non-intuitive markup language to document even the simplest things. Now, there are the ubiquitous Evernote and OneNote, and so many like them; there are blogs and microblogs (is Twitter out of the question for your project?); and if all else fails, there’s email. Find your favorite.
Keep it short. It doesn’t have to be a novel every time you document a discussion. Even if you can’t use Twitter, pretend that you are by being succinct and to the point. What can you say in 140 characters that is descriptive enough to be useful but short enough to get the point across quickly? The likelihood that it will ever be read again is inversely proportional to the size.
Put it where you can find it again. Writing things down doesn’t help you if you can’t find what you wrote down when you need it. Put it somewhere that will be the most obvious place to look (e.g. in an already established project documentation repository, in the same place you put your source code, in an email to everyone on the team), and ideally where it’s electronically searchable. Don’t just write it on the whiteboard in your team area (although you might want to do this in addition to putting it somewhere for the long-term). You might try putting it several places and see where it gets found… you could even collect metrics on what happened to decide on which is the best place! I know, it might sound like crazy talk to some.
It Needs to be a Habit
Developers, particularly Scrum developers, come to work every day to write code, not documentation. However, there are pitfalls to deciding to postpone or avoid writing things down, and they are issues that can cause real pain to the whole development team. Why risk being “that guy” who could have taken just a few moments to capture those important decisions and thereby save the entire team from hours or days of wasted effort? Take the time to write down what’s important when it happens, and put it where everyone can find it. Your team may not always remember to thank you, but it will sure keep them from turning your photo into their favorite dartboard bullseye.
About the Author
Nate McKie is cofounder and CTO of Asynchrony, an IT consulting firm in St. Louis, Missouri. In his role, Nate drives the technical aspects of the company and teaches agile techniques to clients. For more information on related topics, visit www.asynchrony.com.