Swizec Teller - a geek with a hatswizec.com

Senior Mindset Book

Get promoted, earn a bigger salary, work for top companies

Senior Engineer Mindset cover
Learn more

    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
    Published on April 17th, 2014 in Budapest, Docs, Documentation, Travel + Events, Writers Resources

    Did you enjoy this article?

    Continue reading about Writey write about Write the Docs

    Semantically similar articles hand-picked by GPT-4

    Senior Mindset Book

    Get promoted, earn a bigger salary, work for top companies

    Learn more

    Have a burning question that you think I can answer? Hit me up on twitter and I'll do my best.

    Who am I and who do I help? I'm Swizec Teller and I turn coders into engineers with "Raw and honest from the heart!" writing. No bullshit. Real insights into the career and skills of a modern software engineer.

    Want to become a true senior engineer? Take ownership, have autonomy, and be a force multiplier on your team. The Senior Engineer Mindset ebook can help 👉 swizec.com/senior-mindset. These are the shifts in mindset that unlocked my career.

    Curious about Serverless and the modern backend? Check out Serverless Handbook, for frontend engineers 👉 ServerlessHandbook.dev

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

    Want to get my best emails on JavaScript, React, Serverless, Fullstack Web, or Indie Hacking? Check out swizec.com/collections

    Did someone amazing share this letter with you? Wonderful! You can sign up for my weekly letters for software engineers on their path to greatness, here: swizec.com/blog

    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 by Swizec with ❤️