Document or Die!

Posted by bob on July 5, 2014

[This week's post is a guest submission from Jason Schmidt (yes, he's my son). Jason is a far better software engineer than I could ever be. I wish I could say that I taught him this, but he has come to this understanding without my help.]

The DoD Principle (Document or Die) is easily summed up with the short statement, "If it's not worth documenting it's probably not worth doing." Thus the really short form, "Document or Die."

Why should you document things?

There are many positive reasons to document (record, annotate, transcribe, chronicle... you choose the synonym that works for you) something in your life. Here are a few reasons I think are really good. If you have better ones, please share them with me!

You'll remember more

Documenting things will help you remember them better. Many studies have shown that most people learn more effectively by writing things down. As George Santayana said in The Life of Reason, "Those who cannot remember the past are condemned to repeat it."

You have less to remember

Even though you'll remember more details by documenting, you actually have less overall that you need to remember. Here's a nice, simple example for you: What's the chemical formula of chlorophyll a? All I have to remember is where my chemistry book is (or remember that Google will answer simple, well-established questions like this reliably - but remember to apply The C.R.A.P. Test). Let the documentation remember the minutiae for you.

You can share information more reliably and more quickly

Have you ever played the game of telephone? Every time you tell someone information, they turn it into knowledge (abstracted, contextual understanding). When they turn it back into information, errors creep in. These errors are cumulative. If you give someone a copy of documentation or pointer to documentation, then errors will not creep in when passed from person to person.

How long does it take you to tell a story? How fast can you speak? How long will it take if you're having trouble remembering? In contrast, how about if you only need to share a link, copy a piece of paper, or hand someone a book? How quickly can they read it?

It takes far less time and is far more reliable to share documentation, so go ahead and share that blog post you found *hint*hint*

You get a sense of accomplishment

When you finish creating a piece of documentation, even a very rough draft, you'll likely feel good about it. Just because there's more to be done doesn't mean what's already done is useless. If something more urgent comes up and you can't give time to polishing the result, at least you have a result to show.

Remember, in academia, the lowest grade you can get is a zero. Producing no documentation is like not turning in an assignment. You won't get any credit for it.

You lend an air of formality to the topic

Whether or not you're an authority on the topic, you have something that feels much more solid, material, and official. Maybe that impression evaporates quickly, or maybe it is reinforced, but either way you start from a better position. Otherwise, why would you care if someone else on the internet states something you know is wrong?

Who should produce documentation?

You should!

But it's not my job

Then consider it an exercise in self-enrichment. You're making yourself more valuable.

But I'm not in charge of that / don't have permission / don't own it

Well, perhaps you'll save someone else some time. If anyone tries to tell you that you're not allowed to produce documentation, preface the document with, "for personal use only," and make a reasonable effort to keep it private. Also read the section "When should I NOT create documentation" below.

For whom should I create it?

Create it for yourself! That alone is worthwhile. You don't have to create it for your family, friends, pets, coworkers, or anyone else in the world, but if you have a recipient in mind (in my case, often my coworkers), do tailor it to your intended audience(s).

What should be documented?

Well... ideally I would say, "everything," but... that's way too much!

I would propose the rule of thumb: Document everything that you feel is important now or could be important in the future.

When should I create this documentation?

The best time to document something is when it is happening or when it is top-most on your mind. For example, recording notes about a meeting should happen during the meeting. Of course, this isn't always possible, but this is where technology helps us out. This is why I feel confident saying, "If it's not worth documenting it's probably not worth doing." If you can't manage to record a meeting, an activity, a product, a support session, or whatever it is, then its value will be limited to that moment and whatever you manage to remember afterward.

When should I NOT create documentation?

When you're under a legal obligation. Don't copy top secret data unless you know you're allowed to; don't write down patient data anywhere that isn't authorized; don't jot down that credit card number on a sticky note... Use good judgment.

How should I create the documentation?

There are many kinds of documentation we can create. Text is hands-down the most easily organized and searched kind of documentation, but that doesn't preclude the use of pictures, audio recordings, and even video. You should use whatever makes sense at the time, then follow up later if needed.

Here's a real-world example for you: I recently was a participant in an all-day meeting. Set aside any arguments about whether or not such a meeting can be useful, because I want to focus solely on the documentation part of it. I set myself the goal to take my own notes throughout the entire meeting. In the end, I had 171 significant notes. That's roughly 21 per hour, or one every three minutes. That sounds reasonable, right? ... But if you've ever been in any meeting, you know that things aren't spaced out that way. There were long stretches without anything I felt worthy of note, then short, intense flurries of useful information. There was no way I could keep up, but I didn't have to. I used my phone to take an audio recording of the meeting. Every time I felt something might be worth noting, I recorded in my notes the time as accurately as I could. If I had a moment, I'd go ahead and write the actual note as well. Otherwise I'd just put "TODO" next to the time. When it was over, I didn't have to listen to the entire, whole-day recording again just to find the bits I missed. Instead I homed in on them using the timestamps I managed to write down, and just transcribed the bits that I missed. For the period where I was standing at a white-board, I couldn't take any notes at all. I only had the start time before walking up to the white-board, and the end-time when I walked away... But when I walked away, I picked up my phone and snapped pictures of the white-board. After I felt my notes were complete, I deleted the audio recording, because I don't want people afraid to speak out during meetings, and because it would take up at least 50 megabytes of storage (with lossy compression as an MP3 file) whereas the notes themselves barely took up 10 kilobytes (that is 0.02%, or 1/5000 the size).

Where should I put the documentation?

On the web! Okay, maybe that's not always the best place, but consider storing your documentation in a format that is easier to share. Remember to store it in a way that you can find it again later.

Rules of Thumb

I like quippy rules, so here are a few to consider:

  • If it's not worth documenting it's probably not worth doing: Document or Die!
  • Quality is better than quantity; Quantity is better than nothing
  • Document everything that you feel is important now or could be important in the future
  • Use good judgment
  • Use whatever works best
  • If you can't find it later, you might as well not have recorded it

Jason Schmidt 7/5/2014