I’d Rather Be Coding – Writing Things Down

Developers really hate spending time writing, unless what they are writing is 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.

Why Write Things Down?

There are many times in the life of a project when a little documentation goes a long way. But to get those benefits, developers must take time away from coding to write things down.  Here are some examples where I think they will find the juice was worth the squeeze.

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 have good memories and have been with the project long enough, maybe the new team member will 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.

Remember that if you receive an answer like that, you always have a choice. You can keep doing things the way you’ve always done them, because you’re used to the pain, or because 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.  After all, what could go wrong? Well, as it turns out… plenty. For example:

• 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 be 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 might even have a process for making the decision that would produce artifacts you can point to).  Then later, when someone asks the question “why you’re doing things that way or using that tool”, you can answer their question with confidence.

Preparing For Automating An Annoying Process

Developers frequently find processes they want to automate.  These are the ones that they repeat regularly and which waste precious development time. However, all too often I come across manual processes that are performed infrequently (maybe once every few weeks), and involve a series of steps that must be followed in a specific order.  If no one bothers to write this process down, there’s a good chance it will be performed incorrectly or steps will be missed, wasting even more time.  Furthermore, there’s no practical way to automate a process without first writing down the steps.

If you find yourself performing a task with multiple steps – and there’s a good chance you’ll have to do it again, write the steps down. This will save time when the next person has to perform the process manually, 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 a document will ever be read more than once is inversely proportional to its 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 where content was found to decide on which is the best place to store it! I know, this might sound like crazy talk to some.

It Needs To Be a Habit

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.

About the Author

Nate McKie is co-founder and CTO of Asynchrony, an IT consulting firm in St. Louis, Missouri. Nate spearheaded the effort to make Asynchrony a leading practitioner of Agile techniques and ideas and to spread the disciplines of quality code and rapid implementation throughout its commercial and government customer base. In his role, Nate drives the technical aspects of the company and teaches Agile techniques to clients. You can follow Asynchrony on Twitter via @asynchrony and Nate McKie via @natemckie.