The 10 commandments of documentation

Default avatar.
July 15, 2014
The 10 commandments of documentation.

thumbnailToyota 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 +

Read Next

15 Best New Fonts, May 2023

The choices you make when selecting a typeface have more impact on your design than almost any other decision, so it’s …

10+ Best Tools & Resources for Web Designers and Agencies (2023 updated)

Having the ability to envision a tastefully designed website (i.e., the role creativity plays) is important. But being …

20 Best New Websites, May 2023

This month, there are tons of great new agency websites to get excited about. 3D animated prisms are a popular theme, a…

How to Find the Right White Label Website Builder for Your Agency

Web design agencies face a lot of obstacles in closing the deal with new clients. One of the most common ones is the ar…

Exciting New Tools For Designers, May 2023

There are hundreds of new tools for designers and developers released each month. We sift through them all to bring you…

3 Essential Design Trends, May 2023

All three of the website design trends here mimic something bigger going on in the tech space, from a desire to have mo…

10 Best AI Tools for Web Designers (2023)

It’s time to stop worrying if AI is going to take your job and instead start using AI to expand the services you can of…

10 Best Marketing Agency Websites (Examples, Inspo, and Templates!)

Marketers are skilled in developing strategies, producing visual assets, writing text with high impact, and optimizing …

15 Best New Fonts, April 2023

Fonts are a designer’s best friend. They add personality to our designs and enable fine typography to elevate the quali…

20 Best New Websites, April 2023

In April’s edition, there’s a whole heap of large-scale, and even full-screen, video. Drone footage is back with a veng…

Exciting New Tools For Designers, April 2023

The AI revolution is having a huge impact on the types of products that are hitting the market, with almost every app b…

3 Essential Design Trends, March 2023

One thing that we often think about design trends is that they are probably good to make a list. That’s not always true…