Write the Docs, a conference for all those nerds writing your docs, had its first European installation in Budapest at the beginning of April. A two day event of pure awesomeness, great people, lots of banter, shiny surroundings, delicious food, and there were some talks too.
Unfortunately I was too busy creating my own talk to pay proper attention to everyone else’s … hooray for being a responsible adult and coming totes prepared. But the one ear that did pay attention, the left, says they were all great. Even those so deep in the nitty gritty it would be impossible to make them entertaining.
Talks fell into roughly three categories: – docs writing is weird, here are better tools – your docs need the right tone – making developers care sucks
Despite all text handling solutions developers use, docs writing is stuck in ever so slightly arcane ways. But it’s getting better!
I can’t remember any of the mentioned tools mentioned specifically, but there is at least one big boy standard for docs writing that nobody uses, and a lot of cool tools that can almost turn your code into docs. Unlike javadocs, usefully!
Most people just use markdown though so the hard part remains figuring out how to publish documentation, when to publish it, and all the weirdness around making sure it’s correct and in sync with the code.
My favourite line was from Mikey Ariel’s talk agile docs writing – always asking developers “Okay, I have the new build. What’s new?”
That was the commonest concern really. Making sure docs are in sync with the code, not talking about features prematurely, updating things that have changed, and just making sure a developer takes the time look at the technical gobbledy-gok and make sure it’s correct.
Preferably you could run a sort of test suite on the docs …
The other half of Write the Docs was about tone. What do you want the docs to sound like? Should they be funny, entertaining, kind of uptight, or just boringly technical?
Everyone agreed no matter what engineers might tell you about wanting the straight facts and nothing but the facts, they don’t. Documentation with soul is better. Better in that it will be read. Better in that it helps people understand.
Very fine line to tread too. Being entertaining, but not too entertaining. Being cuddly, but not too cuddly. Being hand-holdy, but not too hand-holdy.
The perfect mix depends on target audience. Ideally matches your branding.
But the main thing I learned is that documentarians are awesome. I have never before seen such a friendly and easy to talk to crowd.
Walk into the room and the first person you see goes “Hey” and you just start chatting. Don’t think there was a single person at the whole conference I didn’t speak at least a few words to. Some of us even hung out.
Sure I forgot to ask just about everyone for their contact info, but for those brief two days we were a possé. It was really cool.
And I loved the experience of tweeting out a “Hey anyone wanna grab some dinner before the drinkup?” and we actually did. We grabbed dinner. Like six of us. Amazing.
Oh and the food was baller too. Didn’t see a single pizza the whole three days I was in Budapest. Kudos!
10/10 will go again
By the way, videos aren’t online yet, but you can see a list of talk with slides over at Write the Docs.
Oh and Andrew Spittle wrote an amazing set of notes, here.
PS: You should also follow me on twitter 👉 here.
It's where I go to shoot the shit about programming.