I get to see, as part of my day job, the outcome of generally quite technical people battling with instructions.  Typically those outcomes are bad - unless someone has had a spectacularly good experience with some instructions, you probably won’t hear about it - think here of the iceberg of people who complain, versus those who praise (typically customer service).

This set of thinking has resulted out of a week-plus long battle I have had with a set of (and I flatter it a little here) technical documentation for some open source storage software.  I’m not going to flame the nice people who failed to write it, or make it understandable, but I am going to write some things that I think make better documentation than the other sort.  As you might guess, some of these things have made me a little sweary at times.  I know.  Me.  Sweary.

Assumption is the mother..

S’true.  If you assume I know already what all the components of your application are, and you don’t write it down, what you’ve done is going to be meaningless to me.  If you don’t introduce your subject matter in a way that means it’s consumable, then it’s not going to be.  Consumable, that is.  I like consumption.

Validate your processes..

If you give me a list of steps to follow, I shall follow them.  I shall even cut and paste your code.  When it doesn’t work, I am going to think that you’ve done it deliberately.  Probably out of spite.  If I ever meet you, I will stab you in the face with a spoon and set you on fire.

If it’s broken..

Your documentation is an extension of your code.  No bugger is going to want to implement your code in a mission critical context if you can’t support it. Version control it.  Get people to submit bugs on it, and that way it will improve beyond your wildest dreams because the documentation is going to be written by the same people who will want to consume it.

Check Apache - everything has been documented to the nth degree.  You’d have to either be a moron, or recently descended from a uterus to be in technology and not know what it is, BUT THEY STILL TELL YOU.  Actually, they could tell you what HTTP is - there might be some TLA type recursion there, but I’m willing to forgive them, they’re probably nice people.

What I am proud of, is that the things above are things that we (not going to tell you who, all opinions etc) do already, and do them well.