Documentation starts in the kitchen and ends with your brother

I am all for good documentation. Whether I do it myself is something that I will leave for others to judge me on. I have had a ‘documentation is like labeling your power sockets’ post ruminating in the back of my mind for a while now and then I read this.

Elizabeth Naramore has added to Chris Shiflett’s PHP Advent Day calendar with an excellent piece on documentation.

She makes some excellent points on how documentation can be like telling a stranger to putting the dishes away, how it helps you examine your code, how it keeps you mindful of portability, how it will save you debugging time and how it will save your ass.

I like the anecdotes.

I have my own. As I said, I have been ruminating on this thought for a while but for me documentation is like well labeled power sockets. Power cables are an interface. They interface your stereo, laptop, dvd etc with the power. The problem is, just like parameters, power sockets all look the same. A little blue label can go along way.

I am sure that you have never had get behind some really inconvenient cabinet and change a video over for a dvd and you had no idea which socket was safe to pull out. Whoops, you just pulled out the TV.

I have to do this all the time. I am always pulling out my laptop and moving it somewhere else. Office to client, back again, into power strips neatly organised with 3 neat little friends it can hide next to, retrieving it from a tangle of power cables printer cables and usb cables.

Power cables with labels

It might look a bit silly but when you go to pull out your power a little blue sticker can save you a whole lot of time.

Ditto for documentation. Sure putting that extra little comment in there looks a little silly but 6 months from now you or the guy who comes behind you is going to appreciate it.

I met someone the other day at and we started comparing notes about all the projects we had worked on. ‘Ahh’, she says. ‘I remember your work from client such and such a project. You left good comments.’

Sometimes your brother can be your best friend.

Brother labeller

Anyway that’s enough serious stuff for a Friday night, I have a friend coming over with his X-box and I am going to have to find some power sockets for him.

Advertisements


%d bloggers like this: