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...

Why I want someone else to own my career

"You own your own career"
"You should own your own career"
"You can own your own career"

These three sentences are subtly different in words but hugely in the impact for you as an employee of a company.

Every noticed how successful sports people have two managers? (e.g. footballers).

Their first manager is the one they work for. They do what they are told by this manager. This manager hires, fires decides pay rises etc. You probably have one of these if you are a company employee. This manager works for the football club, cricket team, formula one team or whatever.

Think Jose Mourinho (Man Utd), Toto Wolff (Mercedes F1) or Christian Horner (Red Bull F1) if you like.

The second one is their manager that works for the sports person. This person finds them work, negotiates their contracts and pay rises, manages their image rights, gets them product endorsements e.g. shoes, clothes etc. Sometimes this person is referred to as their agent - for example in acting. They may have more than one of these.

The key thing here is that the sports person concentrates on the sport. They score goals. They win races. They train to score more goals or to drive faster. They concentrate on what their company is paying them for. They work on delivering business value.

They might be the best in the world at what they do - or are trying to be. Conversely, they might be terrible at managing their career. This doesn't matter - they have someone else who is very, very good at it to do it for them.

"Ah" I hear you cry: "You should have a career mentor!".

Nope - that's not the same thing at all. Does my career mentor apply for jobs for me? Do they write my CV? Do the join me in performance appraisals? Do they negotiate salary rises and promotions? No - they give advice as to how I can do that myself.

I admit I'm terrible at that sort of thing - and although I'd like to be better at it (because being better at it might mean I'd be further up the career ladder), I have absolutely no interest in becoming the kind of person who is better at it.

I want to be better at architecting, designing and implementing solutions for my customers. Faster at delivery with higher quality and better responsiveness. Better at mentoring and coaching my team. Better at driving business value. Better at making my customers happier.

So, I'm going to concentrate on that - and I'm also going to go and find someone to manage my career for me. If it's good enough for Lewis Hamilton . . .

Garratt's first law of . . .

Garratt's 1st law of Agile states:

"Agile is a good thing. It's endorsed by major companies and analyst firms. Lots of people are using it."
"Agile projects get funding - usually for the above reasons"
"My project needs funding"
"Therefore my project is Agile"

See also Blockchain, Containers, Cloud, SOA, BPM, Cognitive...

Is your project using the right technologies and methods for the right reasons?

See also Garatt's 1st corollary of Agile:

"Having agile skills is good for my career and pays well"
"I need Agile on my CV (resumé)"
"Therefore we will use Agile on this project"

See also Blockchain, Containers, Cloud, SOA, BPM, Cognitive...

From an alternate perspective, Garratt's 2nd corollary of Agile:

"Many people and companies want to use Agile and therefore have budget for it."
"I need to sell my products and services"
"Therefore my products and services are Agile!"

See also Blockchain, Containers, Cloud, SOA, BPM, Cognitive...