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.
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.
Continue reading about Writey write about Write the Docs
Semantically similar articles hand-picked by GPT-4
- Blogging, hats, stuff
- The real-time WebCamp bash
- #WebcampLj was bitchin'
- Debauchery at BcLj2
- Webcamp Zagreb report
Learned something new?
Read more Software Engineering Lessons from Production
I write articles with real insight into the career and skills of a modern software engineer. "Raw and honest from the heart!" as one reader described them. Fueled by lessons learned over 20 years of building production code for side-projects, small businesses, and hyper growth startups. Both successful and not.
Subscribe below 👇
Software Engineering Lessons from Production
Join Swizec's Newsletter and get insightful emails 💌 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. 👌"
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 ❤️