The 10 commandments of documentation

Toyota is well-known as the most efficient organization on the planet outside of the human body, and one of their philosophies is to avoid documentation. Instead of making a “process” for when someone on the assembly line needs more bolts, they simply have 5 bins of bolts on their shelf and when one is empty they move it off the shelf and someone comes by every hour and refills all the shelves from the back. There’s no need to document anything, the process does it for you.

There was a recent article on Quartz which talked about Apple’s attention to checklists.

It turns out that the key to Apple’s creativity, speed, and adaptability is, on its surface, the exact opposite of the kind of free-wheeling creativity one might expect. It’s a checklist…a really long one.

Which got me thinking about what my philosophy about checklists is. There’s a lot wrong with checklists. They get out of date. They can be long and boring and repetitive. Like all metrics they can focus on the wrong things. But all of those things are true of skipping checklists too, right? I mean the third time you’ve made the same mistake it’s probably time to admit that following a checklist might have saved you time.

But checklists are only good if they apply and they’re updated often, and you’re still at the whim of a human who, let’s face it, aren’t built to be perfect all the time.

Real world problem

We have a standard Drupal install we start with for most clients who are on Drupal. This includes modules, settings, default users and our default test data. It used to be a checklist, but it was always out of date. Then someone went in and made it so specific that anyone even with limited knowledge of Drupal could do it, so all the die-hard Drupal people in the shop hated it, so we took that out, and then we couldn’t train anyone new on it and only senior Drupal devs could follow it, so then we started hard coding it in Drush.

Drush means that anyone with Drupal experience could run a couple of lines of code and everything would “happen” magically. No more “human error”, it’s a checklist, but instead of a messy human trying to follow a checklist, a computer followed it.

The problem with that was that even the simplest change needed a developer and every change had to be tested and so it fell apart pretty quickly.

Eventually we came across the obvious solution, which is something hard-coded in Drush, which made it somewhat hard to change.

Now we simply have a site called “clone me” or something like that and whenever we have a new client we just duplicate it. Changing it used to involve a programmer and lots of other work, now anyone with the password on our team can go and change something. If a designer wants different test data, they change it and it will automatically be in our next project. If a PM decides we need another default user for training purposes, they create one and it will be in our next project.

“The first time you do something just do it. The second time, do it and take notes. The third time, stop and see if it’s really the same. If it is make a process out of it because there will probably be a 4th, and 5th, and so on.” – Gavin Andresen, CTO Bitcoin

We were lucky enough to have Gavin here at Gravity Switch for a few years. He contributed quite a bit to our culture and our code, but his wisdom about when to “hack” things and when to proceduralize them is something that’s really changed how I approach documentation.

Gavin taught us that good code is self-documenting.

The 10 commandments of documentation

1. Thou shall not over-document — If it takes longer to document than to do, you’re over-documenting.
2. Thou shall automate before document — Take out the human factor whenever possible.
3. Thou shall not muddle through the same thing three times — If you’ve messed up or had to figure out the same thing twice, it’s time to proceduralize.
4. If it’s going to fail, make it fail big — The trickiest things are the things that you miss the first (and even the 10th) time you review them. If you have a choice between creating a process that will stop the assembly line or crash your site if it fails or one that will create a slight error, always choose “take down the site” because at least you’ll spot the problem first time.
5. Thou shall put the process where one must trip over it — because it needs to be found.
6. Own it — When following a process, keep in mind your job is to produce the best result. It’s not to follow the process. Always approach it with skepticism and look critically at the results.
7. Admit when it’s not working — Sometimes things might look the same, but they’re not. In our world, we always need standard test data, but the process for creating that in WordPress is completely different than creating it in Drupal, so we need completely different processes.
8. Fix it fast — If your process is out of date, don’t just ignore the issue and wing it, or pick and choose the parts you want to follow. Fix it as you go. It will only take you minutes longer to do in most cases, and those minutes will turn into hours next time you or someone else uses the process.
9. Pick your battles — Steve Krug (the master of usability) says you should test often. Find your biggest problem. Do the LEAST amount of work you can do so that it’s no longer your biggest problem and then repeat. You’re not trying to get any little kink out of the system, you’re trying to get the WHOLE system to run better.
10. Revisit — If you’ve used a process a dozen times and haven’t changed it, you should think about how you can make it more efficient or if you should just automate it.

Jason Mark

@JasonOnDesign: co-founder of Gravity Switch, frequent contributor to popular nerd blogs, and dynamic speaker on topics such as web & mobile development, graphic design, and project management. In a past life he was one of the first professors to teach internet strategy and web design at a graduate level. His passion? Helping people "take it to the next level". Follow Jason on Google +