Just write it down

A friend of yours walks into a local software firm at 2:30 on a Tuesday afternoon. Never having been there before, they won't know what's going on. They'll see people working; they'll see people typing. It'll be pretty quiet -- there'll be some people talking over an idea here and there but mainly people are facing their terminals with their hands on their keyboards, and they're working really hard.

The question is, What are they doing? What's really happening? What is it like inside the heads of those developers? What is the stuff that they do all day while quietly typing? I'll tell you (and this has been true everywhere I've worked, the bad and the good): all day, every day, they're stumbling, and they're staggering, and they're swearing. And the reason is that they're trying to build things. They're still building things because those things don't work yet. And the things don't work yet because they're trying to figure out how to put the pieces together.

This is where the time goes. This is where the budget goes.

I saw a magazine ad years ago which had a red sports car on a highway with red lights every fifty feet. I think that's what life is like for us most of the time.

The reason we don't understand how things work is because -- last year, last month, or even yesterday -- we didn't explain our hard-won lessons to one another.

My suggestion to you is to simply write it down. Write it down now, in a way that's just good enough for tomorrow. You can start small -- you don't have to write something as long as Moby Dick and it doesn't have to be perfect. The goal is just to save your co-workers a difficult day tomorrow or next week. Imagine one of the people near you and make their life a little bit easier.

I want to acknowledge barriers as well as solutions. These are two different things. I think the conversation is mainly about barriers. One set of barriers is when we say: I'm not good at writing, I don't like to write, I don't understand how the wiki tool works, I don't have any time, Not right now, I'm busy, I have another project to move on to -- or (worst of all) Perfection is unattainable so why bother.

Another set of barriers is when we say: We're here to build solutions, not documents. My counter-argument is that our solutions baffle us when we have to modify them or debug them not very far down the road. Development time too often is just code archaeology. Much of it is not really development in the sense of creating something new, but rather re-discovery. There's this Thomas Heller quote that I like, that in every company there's at least one person going crazy. I would say that most of us are going crazy. We let ourselves get used to this continual re-deciphering of things and we accept it as ordinary. But it doesn't need to be.

What are some solutions? You can start small. You can simply ask yourself, What took me a lot of time this week? What was hard? Where did my time go? What did I wish I hadn't needed to do? What did I wish someone had just come out and told me up front? Those are the kinds of things most worth knowing. In terms of the cost of time, those are some of the most valuable deliverables you can offer. Write down the command you could never remember how to type, the data-update sequence you kept doing out of order, the steps for viewing the database-table schema. Make yourself a little cheat sheet for next time and put it where other people can see it. The deliverable is not only the software solution but also the knowledge of how you got to the solution.

There's a saying that the best time to plant a tree is twenty years ago. Fortunately we don't need twenty years -- weeks and months are just fine. And documents can live. You can cross-link between source code and wiki pages: simply have each one give the name of the other one. People will find them; they will stay alive and they won't become stagnant.

Write it down, and make it just good enough for tomorrow. This afternoon, take fifteen minutes (no more). Take your last project. Write down the purpose of the project and the top three gotchas. Make a few paragraphs and push the save button. Those fifteen minutes today can save more than fifteen minutes on your group's subsequent projects.

There's no single magic solution to all problems in software development. But the way I like to envision these little bits of solution-recording is reaching down the road ahead and, each time, flipping a few more traffic lights from red to green.