I'd Rather Be Coding: Writing Things Down

For a long time, I’ve been wanting to write a series of posts about those little activities that are a critical part of Agile and Lean, but somehow seem to slip by the wayside even on the most competent teams. This series is entitled “I’d Rather Be Coding,” and recognizes that the team is trying to do their best but sometimes needs a reminder about what is important.

Developers really hate writing things that aren’t code. They have good reasons for this distaste, however.

If it’s not code, it can’t be run through a compiler to make sure it makes sense.
If it’s not code, it doesn’t get executed, so it may never be used to accomplish anything.
If it’s not code, it can’t have tests against it, so there’s no way to prove that it is truthful and correct.*

Agile even de-emphasized documentation in the Manifesto:

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

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 (hopefully 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 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. Not much effort, and 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. 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). Maybe try putting it several places and see where it gets found… you could even collect metrics on that to find the best place! I know, crazy talk.

It needs to be a habit, or it won’t happen

As I said, documenting these little occurrences in your everyday project life is not going to be natural; you’re going to have to force it. I know you’d rather be coding, but make yourself do it; I promise it’s worth the effort. If you make yourself jump right to your note-taking system the moment something happens, pretty soon it will be second nature. Then you’ll wonder how you ever got by without it. * Okay, that’s not totally true, but it’s only the rare case when someone writes tests against documentation. I know these cases exist, because we’ve done it before, right Myles?

3 Comments on this Post

nate.mckie

Author/ June 20, 2013/

Thanks for the feedback, Craig! Yes, having a place to put things where everyone can find them is very important. If you can make the code repo work for that, great; I’ve not seen anyone do that effectively yet because of the issues of searching through it. Maybe you can share your ideas if you come up with something good.

Metrics link fixed; thanks for the heads-up.
Craig Buchek

June 20, 2013/

Excellent article, Nate.

I’d already come to the conclusion that we need to document a lot of the decisions that we make during a project, but have not been able to come up with a good way to accomplish that. I think having a place where such documentation “belongs” would be a good start. (For me, that would usually be somewhere in the code repository.) Having it as an item on the code review checklist would probably help as well.

PS. The link to the metrics article is broken.

One Trackback for this Post.

By Episode 18 – Continuous Groundhog Day on June 26, 2013 at 10:48 pm

[…] Blog Post – I’d Rather Be Coding – Documentation […]

Comments have been disabled.

I’d Rather Be Coding: Writing Things Down