THE TECHNICAL AUTHORS' VALLEY

Well, another day, another presentation in which I look dolefully at my boots and wonder what in the world is going on.

I don't think it's down to presentation skills. I think it's down to content. And so while the roomful of developers watches a black screen with white digital code flashing by, accompanied by a narrative that might as well be in Swahili, I wonder once again what a Rest API is, how to generate unit tests and why I'd want to output JSON or XML files and (crucially) why I'd care about it. It's a mystery, but as a technical writer, it's my...

professional duty

... to remain as distant as possible from the cogs and levers and commands and plugins. And so I should. Probably.

It often seems that we work in the valley between two tribes out here in the docs team. And these two tribes know exactly what they're doing of course, but have entirely no empathy for the other.

Like dutiful mediators, we technical authors saddle up to Developer Land with our notebooks, and we carefully scribble down exactly what they tell us. Then, we scurry back and write it out properly, before scuttling up the other side to Customertopia, where a baffled group of people try to make sense of it without looking cross.

The Customertopians of course, send us back with lots of questions, some of which might just turn out to be risible on the yonder hills. Wearily, we trot back down between the lengthening shadows.

Then at night, next to our wooden huts, struggling to keep warm by the firelight under the stars, we hear the sound of wailing and we suddenly realise that we can never quite tell where it's coming from.

-

Er. I might have stretched that metaphor a little too far. But that's what happens in meeting rooms where you don't get a single word of anything that's being said! You end up drifting! Wittgenstein was right - if a lion could talk English, there's no way we'd understand it! And in a roomful of developers, me and the lion would be lost together.

Though, I bet the lion would be a bit bolder than I was about getting out of it.

"Any update from docs, Matt?" asked someone, suddenly rousing me from my daydream. The presentation had ended and they were circling the room for our team news and status.

I blinked and then started talking. I've got no idea what I said but it must have sounded good.

Bring on the lion, I thought to myself.