This article is more than 1 year old
BOFH: Is everybody ready for the meeting? Grab a crayon – let's get technical
Mindfulness worksheets? Lattes? We're all set
Episode 11 So I'm doing some documentation – which we all know is a waste of my valuable time because everything I do is self-documenting – and the Boss walks in.
"How's that documentation coming along?" he asks, looking at a long list of items on his personnel disorganiser.
"It stopped the moment you entered the room."
"Well I just want to be sure that you're onto it."
"You may rest peacefully in the knowledge that I am."
"And run them by me when I'm done – just to make sure we're on the same page."
I doubt that the Boss will make it past the table of contents page, but I have to make sure.
"You know this is a technical document, right?"
"Made for technical people?"
"People who would have to take over my role in the event that I stepped out in front of a bus. Driven, most likely, by the PFY?"
"..Who wouldn't need the documentation anyway."
"Yes – your point?"
"Well this is a technical document which doesn't go into long explanations about technical details."
"And so I either write the document for: the person who would have to pick up the reins; the person who employs the person who picks up the reins; or, for the person who shovels the horseshit out of the way so that people can get to the reins."
"And which do you think I am?"
"I prefer not to answer that but suggest you wear gloves to work. As for documentation, I know only 3 languages, Technical, Plain English and Idiot. The less technical the documentation is the longer the documentation tends to be..."
"And which language do you think I read in?"
"The same language you use to email me," I say evasively.
"Have you ever noticed how long your email messages to me are?" I ask "And how long my replies to you tend to be?"
There, I said it.
"So which language do you mean?"
OK, so I said it, but in plain English.
"Idiot," I say.
"What?!" the Boss seethes.
"It's OK, though," I explain, "because a technical manual is for technical people. It's not meant for an audience without the acumen to understand it. You wouldn't expect to open a textbook on knot theory and understand the mathematical equations therein would you?"
"I suppose not," he admits grudgingly.
"And so in a similar way you really can't expect to understand the nuances of domain synchronisation, virtual machine tuning or even cryptographic key manipulation."
"You may be right," he sighs, wandering up to look over my shoulder. "What are you writing about now?"
"How to get good onion bhajis at lunchtime."
"The onion bhajis. To get the best ones you need to wait for the first batch to go through as they're probably reheated ones from the last time bhajis were on the menu. That said, you need to be in the queue when they resupply with fresh bhajis. Ideally you need to be six people down the line when the dish gets to about a third full of the first batch so that the fresh bhajis are served just as you get there."
"What the hell has this got to do with technical documentation?!"
"It's documentation for an IT professional – we like our lunches."
"And that's something that I wouldn't understand is it?"
"You always eat from the first batch," I point out. "QED."
"This documentation better not be all about meals!"
"YOU said I had to cover all aspects of my role!"
"So what were you working on this morning when I came in?"
"Timing your pub visit to get the 10th pint from a fresh keg."
"It's technical!" I say. "You wouldn't understand. Dave is the one who changes the kegs so when he's gone from the bar for more than 10 minutes – and he's not in the toilets – he's changing a keg. You don't want to try the stuff before then because it's often a dilute blend of lager and line cleaner – which is why the PFY and I usually drink bottled beer till you lot have had a few pints."
"I told you it was technical."
"What about that domain stuff you were talking about?"
"You mean all the geeky stuff? That's already in manuals. No need to reinvent that wheel. No, what I'm documenting is the important stuff that is critical to the smooth operation of the IT systems – like you asked. Which pizza places are open 24x7 and are happy to write you a receipt for 'office supplies' on their ghost company's letterhead. How to move all the clocks in the building 20 minutes backwards on a Monday morning and 40 minutes forward later that afternoon. How the lock on the pivoting windows can be adjusted so the window flips open the moment someone leans on it."
"That's not a thing."
"Sure it is. So is changing the acceleration/deceleration curves on the lifts; tinkering with the heat and humidity settings on a single aircon unit for a 20-minute period to make the annoying woman in accounts receivable think she's going through menopause; making the maglock release times just a bit longer so people never know exactly how long the door will take to release, etc."
"That's not useful information."
"Of course it is. Why do you think you keep crashing into the door when you're carrying a scalding hot coffee?"
... the next day...
So the Boss is in a foul mood about the whole documentation thing and as a result he's punishing the PFY and me by making us attend a meeting with several of his grizzled ex-workmates from his former life in IT sales with a view to putting our latest server project their way...
As you'd expect, it's a collection of 30+-year-old war stories from 60+-year-old sales types who know more about the bottom of a gin bottle than any computer made in the last 25 years.
"... but it didn't matter BECAUSE SHE DIDN'T KNOW HOW TO LOG IN ANYWAY!!!" one of them blurts to the amusement of the others.
"Wow," the PFY says. "You guys have some great stories. Wish I was a degenerate alcoholic."
"Now then," the Boss says in calm tones. "They were different times."
"Yes, so much changed after the industrial revolution," the PFY adds drily.
To be fair, the PFY has a point. The meeting has been a blend of the kind of misogyny and racism you'd expect from a major political leader rather than someone who lives in the 21st century.
"Anyway," the Boss says, "the chaps are excited to hear about this project we have coming up. So if you could just outline it for them."
"Outline which bit – the basic idea," the PFY says, pausing for effect, "or the technical detail?"
"The TECHNICAL detail," the Boss seethes.
"I'll just go get the crayons then," I say, stepping out of the meeting for a moment. Or 100.