Harald Mueller and I have been having a little mailing list debate about documentation. I've been taking the position that we want understanding, not documents. He's been saying that documents are one good way to get understanding. So far, we haven't gotten on the "same page" yet, but I trust that we will if we keep going. In the light of that conversation, though, here are some thoughts on documenting this little product we're working on.

What Should We Write Down?

Well, if my purpose is to communicate with you, I have to write down a lot, because you’re not sitting at Panera with me while I work on this, nor in my living room. (Thanks for not being there.) However, in writing this down, I know that I’ll be telling you too much in one place and not enough in another. And that person next to you, reading the same stuff, doesn’t agree with you on what’s too much and what’s not enough. That’s the fate of anyone who writes.

When I described the learning from the previous article to Chet, who was at Panera, it went much faster. I drew a picture in my notebook, and talked about it. Had I had my computer along, I could have shown him the code and the pictures, and it would have gone even better. Either way, the conversation helped a lot and was much easier than writing the article.

But wait! Did I say “notebook”? What’s that about? When I’m working on a project, I write things in my notebook. I usually use a spiral-bound, 5x5 quad-ruled 8.5x11 notebook. I go through a notebook in one to three months, depending on what’s going on. I have a basement full of them, because I generally keep them. I don’t usually look at them, mind you, but I do keep them. Someday there’ll be a great conflagration made possible by all that paper in my basement.

In the notebook, I write all kinds of things. I keep the notebook with me much of the time, and when I’m having a chat with someone I’ll draw pictures in the notebook, and take notes. If our thoughts digress, so does the notebook. It’s kind of a log. When I’m working alone, I often write articles or chapters in the notebook. And when I’m working on a product, like this map thing, I write down ideas, questions, thoughts, as I have them. The notebook is a journal, a log.

What About Cards??

Wait, Ron, aren’t you the guy who says to put all the stories on cards? Yes, I am. And when it comes to stories, especially stories when I’m working with a group, a customer and some other programmers, I will in fact write them on cards. That will facilitate the social aspects of planning, estimating, prioritizing. Some of the information on the cards will come from my notebook. Some of the information behind the cards will be in the notebook: details that I write down so I won’t forget them. Much of the information on and behind the cards, however, will come out in the interaction between the other team members and me. Some from the notebook, some from the situation.

I find that when I try to keep a large project on cards, I get too many cards. I currently have about 500 cards for one project that I’m working on, and that’s too many. It would be too much information written into one of my notebooks, also, but it would be too much in a differently organized way. The cards are too flexible: they can appear in any order. The notebook isn’t flexible enough: it appears in only one order.

Mostly, I use the cards for social purposes, and because I can always have a stack of them in my pocket. I use the notebook for continuity, for work that persists over time. I’ve never found the perfect balance. Probably that’s part of the reason I continue to have this fascination with pen computers: I’m trying to find some technical solution to this human problem I have.

But I digress … and this article is already a digression.

What to Write Down, and Why

Here I am, a guy who publishes his every thought, and yet I claim to be a low-documentation person. What’s up with that? We need to distinguish purposes.

When I’m communicating with my customer, my programming team, my students or consulting customers, I’d rather communicate in person, face to face. I’d use words – lots of them, if I know me, and I do – and I’d use pictures, cards, gestures. I’d use song and dance if I were up to it. But mostly conversation, aided by the other things. If the other people in the room wanted notes, and I certainly hope they would, I’d like them to keep the notes.

Now you might be thinking defensively right now. If you write the document that describes the outcome of the meeting, you might be thinking that you have better control over potential misunderstandings. You might be thinking that you could point back to the document, say “See, this is what we agree to,” and be better off than if someone else writes the document, and points at it. That’s contract thinking, and there’s a place for it. However, the Agile Manifesto says that we prefer “Customer collaboration over contract negotiation.” That’s what I’m talkin’ about. When what I care about is that we all really undersand each other, we’ll talk a lot, and we’ll all keep our own notes. When we misunderstand, or forget – and we will – we’ll come back together for more conversation, rather than turn to our notes.

Yet, at the same time, I do keep all kinds of notes. Notes on cards, note in my spiral notebooks, notes typed into my computer, notes all over. The primary benefit of all those notes is that I have to think about the topic, so that I can write down something more or less sensible. A very secondary benefit is that I can refer back to them. I do refer back to them, but except for the notebook immediately preceding the current one, I go back exceedingly rarely. Once or twice a year, I’d guess.

So what’s the bottom line? You have to choose for yourself. For me, it’s something like this:

  1. Prefer face to face conversation for reaching understanding and refreshing it when it fades or needs elaboration.
  2. Prefer your own notes, in your own favorite form, for keeping track of things you don't want to forget.
  3. Document more formally to communicate with people who are a long way away in space or time. Expect this not to work very well.
  4. Document contracts of understanding only under duress. Trust your common objectives, and your willingness to work together, not your lawyer.

Your mileage will surely vary. Take these ideas as a place to start while you develop your own position – and expect your own position to vary.