Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage Articles I’d Rather Be Coding – Writing Things Down

I’d Rather Be Coding – Writing Things Down

Lire ce contenu en français


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.

Rate this Article


Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Community comments

  • Excellent article

    by Francois MAROT,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Excellent article, thanks ! I completely agree that writing things down has a lot of advantages often undervalued.

  • Alas, the difficult stuff is only mentioned as side note

    by Dirk Detering,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    I indeed like to take notes and document things. But my experience with projects is not that things are not written down but are written down without some sort of "knowledge management" in mind. Meta-Info? Tagging? Categorising? Thinking about the correct title? Don't have time for this! I've written it down, what else do you want from me??
    So the really difficult part was hidden in the much too short "ideas" part:
    How to find things (and not get drown in search results)?
    How to link and organise knowledge (the basics of wiki usage vs. SPS and the like)?
    And: How to get notified when the basic assumptions that led to decisions change?

    Much too often the project leader asks anxiously "did you document it?" and is satified with a simple "yes". And after 2 years a new doc tool is introduced because no one can find anything in the old tool. (BTW: Email is the WORST solution for persisting and querying knowledge!)
    Unfortunately the people that introduce the new tools don't know them enough and are not the same that use them intensively later. So they become knowledge-sink 2.0.
    (And do you really think a twitter-like tool helps here?)

  • OCD Coder

    by Stuart Zahn,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    I knew someone who had to cursively write his thoughts down on paper every time I explained a line of code to him. This made code reviews and overviews really stressful. Imaging having to start on an idea, then wait for 45 seconds before resuming your thought.

  • And the #1 Reason is ...

    by Robert Crocker,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    In my experience, the most useful reason to write it down is to clarify my thinking. Something about putting a thought in written word forces it to be more precise and more accurate.

  • Great article...

    by Andrew Huntley,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    This is a very good article and has some very valid points. The only thing that I think could be done differently is that the developers should not necessarily have to document things. Code comments are a necessity, but in terms of documenting decisions, processes, etc, that should be the responsibility of the technical / team lead. It is generally up to them to make decisions surrounding what is being developed and how and it is this that puts them in the best position for that. If there are side conversations that are happening between developers, then they should nominate the person who is going to take the conversation notes - if any - to the lead, either for vetting or filing / documenting purposes.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p