Documentation.

Copy this link for a short URL

July 8, 2009 at 12:06am

So I’m rocking this Discovery Album like it’s Radiohead day at Pitchfork Media, and I thought to myself, “what would be a great non-sequitur to introduce a series about documentation?”¹

Yes! Your excitement is palpable! I can feel it with every GET request you are making. Documentation is something we all love doing, right? It’s what drives us to build: so we can write! It’s in many ways, the essence of our enlightenment, the existential question answered, our Nirvana.

Come as you are

Riddle me this. You’ve handed off your client project or you’re working on your start-up. You built functionality fueled on coffee, adrenaline and whip-its with no recollection how it finally came to be. How do you explain what the hell you did?

Whoops. You forgot to write documentation. It works, but it needs to be used and modified by others.

Insert Documentation

Documentation, from a client, or for another developer is important. If you’re sharing code or developing a client site the amount of effort follows the 80/20 rule. For the 20% of the effort it takes, there is 80% reward… and cake!²

But what does developer documentation mean?

Let’s say you have a function call, for example (PHP):

Your trusty partner, developer Higgins, understands that this function is returning something, and that it’s called q, but has no idea what to expect. He’ll have to use functions to find out how this function works. That’s not very DRY nor flexible.

How do you solve this problem?

Here’s a great example of a simple piece of developer documentation that takes 30 seconds with a Textmate snippet (again in PHP):

Doesn’t that look better? Doesn’t that excite you to use this function and see what sort of tales, proverbs and quotes are available to you from Narnian lore?

Yes it does. Developer Higgins is most-pleased, most-pleased indeed.

Clients

Scenario 2nd, same as the first: A little bit louder and a whole lot worse!

You just spent 7 sleepless nights finishing up a client project. “Wonderful!” you exclaim, “My time here on this earth is near completion.” You hand it off to the client and are exalted for such an amazing project. “Truly, no greater deliverable has ever arrived at my IT deployed IE6 browser.” There is lots of hand-shaking, parading around the office with beer-box hats, and funny tweets about someone’s mother.

Then, the next day, the client sends an email: “Um… how does it work?”

Balls.

You forgot the documentation. Just like “dude, you’re getting a Dell”, “dude you forgot the docs” is synonymous with getting a piece of shit.

“But we have client training!” you cry as the day fades to darkness, “We told them how to use it.”

It’s nothing personal, but no one listens to you after 10 minutes in “training”. No one remember 6 hours on a Tuesday after lunch. Also, you look funny… which is a little personal. The minute you show a form field and explain “This is what…”, it is more than likely your client is dreaming of cleaning the dishes.

Building good client documentation is about writing and simplifying the system’s technical implementation. It is about communicating, and if your marriage is to survive, it is a must.

A look on both sides of the mirror

This will be an ongoing, bandied-about series that appears randomly. It will focus in on many different types of documentation with the two larger areas being client & developer.

So we begin tomorrow with a look at CSS & HTML documentation: where rarely does documentation dare to show its face.

May your day be self-righteous and as great as you think you are!

1. Coincidentally, this question removed its “non-sequitur” status. Also, that’s an Amazon Affiliate link. I want your money.

2. Cake is never guaranteed, but should be considered as a required expense.