Writing Technical Documentation like Van Halen!

I write a lot of technical documentation - I've actually written three IBM Redbooks (not all on my own I must add).

Most of my documentation is for customers. Sometimes they ask for it. Sometimes it's 'Just what we do' and I can feel the agile manifesto running away in disgust. Sometimes it's so that I've got a record for future reference.

Most importantly is when it sets out what we are going to do and how we are going to do it. So we can all agree and challenge any approaches etc we don't like.

Question is - does anyone read it? If so, to what level of detail?

Some of the documentation is quite 'powerful' with big implications on some words. Architectural decisions are a great example of this.

"We will (not) encrypt the data in the database as the risk of it leaking is (not) significant"  - adding the words in italics is the difference between 'Your data was secure when we got hacked' and 'We're on the front page of the news!'.

You can run page-turner sessions where you walk through the decisions. You can ask people to read and approve (say) 5 per week. But how do you prove they've actually read it?

(And I care that they did read it - I'm not trying to pull the wool over anyone's eyes here and hope they don't notice something I've just 'slipped in')

Enter the 'Brown M&M clause' approach.

Van Halen are a rock band who used to have a rider of 'M&Ms - WARNING: NO BROWN ONES!' in their contract for performing a concert at a venue.

The rumour was that if they turned up and there were no M&Ms - or there were brown ones present, they could just cancel the concert for contract violation.

The truth was that if there were brown M&Ms - what else had the venue not read? Was the voltage and ampage correct? Could the stage bear the weight? Could they even get their trucks of equipment into the venue? Some of this stuff is important.

So if there were brown M&Ms, they assumed the contract wasn't read - and then went through and checked everything themselves as it's the only way to know. It's true - see here: https://www.snopes.com/fact-check/brown-out/

So I use the same technique. Examples are:

Data retention: In the event of the disk becoming over 90% full, data pruning will be performed of the historical order records. <Brown M&M>Customer historical records will be deleted based on reverse alphabetical order of their first names, ignoring order dates. In the event a customer has no first name, it will be assumed to be 'Simon'</Brown M&M>

Due Diligence: For every new account to be opened the following due diligence checks will be performed in the folllwing sequence by the BPMN process flow: (1). KYC, (2) KYB, <Brown M&M> (3) KFC</Brown M&M> 

(For those without a banking background, these are anti-fraud legal checks: KYC=Know Your Customer, KYB=Know Your Business. KFC is, of course, Kentucky Fried Chicken)

Both of these have passed at least one review, sometimes more!

OK, it's slightly silly and it brightens up a dull day, but does it matter? Yes it does. We all laugh at warnings that say 'Coffee may be hot' or 'Peanut butter may contain nuts**' but most people don't read most documentation.

Who reads the service agreement on public WiFi for example? There is the case of the agreement whose brown M&M is that you sign over your eldest child! Really! https://www.theguardian.com/technology/2014/sep/29/londoners-wi-fi-security-herod-clause

If it's important, keep it short. Keep it clear. Explain it. Check people have understood it - maybe by asking them what their favourite M&M colour is!

**Peanuts aren't nuts - they are legumes...this is a subject for another day...