Skip to content
Swizec Teller - a geek with a

Writey write about Write the Docs

Bagpipes lightning talk
Bagpipes lightning talk

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.

Mikey Ariel talking about agile docs
Mikey Ariel talking about agile docs

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.

Write the Docs group photo
Write the Docs group photo

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.

This what I look like giving a talk
This what I look like giving a talk

Enhanced by Zemanta

Did you enjoy this article?

Published on April 17th, 2014 in Budapest, Docs, Documentation, Travel + Events, Writers Resources

Learned something new?
Want to become a high value JavaScript expert?

Here's how it works 👇

Leave your email and I'll send you an Interactive Modern JavaScript Cheatsheet 📖right away. After that you'll get thoughtfully written emails every week about React, JavaScript, and your career. Lessons learned over my 20 years in the industry working with companies ranging from tiny startups to Fortune5 behemoths.

Start with an interactive cheatsheet 📖

Then get thoughtful letters 💌 on mindsets, tactics, and technical skills for your career.

"Man, love your simple writing! Yours is the only email I open from marketers and only blog that I give a fuck to read & scroll till the end. And wow always take away lessons with me. Inspiring! And very relatable. 👌"

~ Ashish Kumar

Join over 10,000 engineers just like you already improving their JS careers with my letters, workshops, courses, and talks. ✌️

Have a burning question that you think I can answer? I don't have all of the answers, but I have some! Hit me up on twitter or book a 30min ama for in-depth help.

Ready to Stop copy pasting D3 examples and create data visualizations of your own?  Learn how to build scalable dataviz components your whole team can understand with React for Data Visualization

Curious about Serverless and the modern backend? Check out Serverless Handbook, modern backend for the frontend engineer.

Ready to learn how it all fits together and build a modern webapp from scratch? Learn how to launch a webapp and make your first 💰 on the side with ServerlessReact.Dev

Want to brush up on your modern JavaScript syntax? Check out my interactive cheatsheet:

By the way, just in case no one has told you it yet today: I love and appreciate you for who you are ❤️