Swizec Teller - a geek with a hatswizec.com

    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!

    Yes!

    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 an expert?

    Here's how it works 👇

    Leave your email and I'll send you thoughtfully written emails every week about React, JavaScript, and your career. Lessons learned over 20 years in the industry working with companies ranging from tiny startups to Fortune5 behemoths.

    Join Swizec's Newsletter

    And get thoughtful letters 💌 on mindsets, tactics, and technical skills for your career. Real lessons from building production software. No bullshit.

    "Man, love your simple writing! Yours is the only newsletter I open 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 14,000 engineers just like you already improving their 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: es6cheatsheet.com

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

    Created bySwizecwith ❤️