Read Me, Please

One of the great things about Twitter is that, if you follow other curious people, someone is always sharing something interesting that I might not have otherwise found or have had any reason to know about, like 18F’s Open Source Style Guide.

I’m not a software developer nor do I work with open source code.  But I appreciate documentation done well, let alone when it’s done at all.  It’s fun to build new things–like figuring out a new process or procedure–and taking breaks to write down what you did and how you did it and why you did it that way can feel like a tedious chore that slows down all the fun progress.  Plus, sometimes it seems pointless because nobody ever reads it but you, and you already know all those answers.  Especially when they keep asking you the same question repeatedly after all the trouble you took to write down the answer in a shared location!  Sustainability of operations if you were to get hit by a buswin the lottery can only be so motivating for so long.

Then again, there are plenty of times, particularly with complex processes and tasks that I only need to do a couple times a year where I’ve kicked myself for not taking better notes at the time.  (Are these numbers significantly down from last year, or am I forgetting to include something that was included last year?  How did we define this again?)  Deconstruction can be fun, too, but it’s one thing when you’re looking for parts to build something else.  It’s another thing to have to reverse-engineer how you did something last year because you need to do the exact same thing again and you can’t remember how and your deadline is chasing you like Captain Hook’s crocodile.

Okay, but why start documentation during?  Why not after?  It can also feel pointless when you’re trying to document a process in the midst of creating it, and subsequently adjusting both a million times.  You took all this time to write up all the steps and definitions and one afternoon later, half of it is out of date.

The past two weeks, I’ve been plugging away at a new process and a Read Me document of sorts.  And next week, I’ll need to update that Read Me document to reflect all the adjustments I had to make while actually doing what I had imagined doing when writing that document in the first place.  Maybe nobody will ever read it but me, but it’s a starting point to which I can always refer back.  And all my annotations to the first draft will be saved in my files for when I question why something is that way.  Because I will.  And because if I don’t, then I will definitely need to know.

When I was a kid, I did all my math homework in pen.  It drove my teachers up the wall because everything I turned in was always three or four pages longer than my classmates’ assignments due to all the times I’d cross out my work and start over on a problem.  Plus, in addition to reading my handwriting, they had to read past all the scratch-outs and find the right answer.

There’s always one more edit, one new change, some circumstance we hadn’t anticipated or planned for originally.  We wait and we’ll never do it.  Besides, if you take thorough notes, including all the things you tried that didn’t work, then you won’t forget and make the same mistake twice.  Pencils are forgiving, but they won’t give you a trail out of the woods.