I loved WriteTheDocs Europe 2015

I loved WriteTheDocs Europe 2015! Roll credits! … let’s start from the begin, though. WriteTheDocs is a community around technical writing that also organises meetups and conferences. If you know the documentation hosting platform ReadTheDocs, it’s by some of the same people and both things are to some degree interlinked. Having no documentation-centric meetup group in my area I was completely excited when I first learnt about there being a conference scheduled for the first week of September in Prague. Planning started immediately!

---

The Why

For me, documentation is an implicit part of the job. My actual job-description says “software developer” but IMHO you can’t get around also documenting what you’re doing unless you don’t want anyone (including yourself after a week) being able to use it. For me, personally, that means writing simple READMEs for my hobby projects before even starting with them to helping with internal and external documentation at work using tools like Confluence and Sphinx, and tons of other things in between. It’s also something I enjoy a lot as it helps bringing certain design aspects and potential problems to light in a similar way that pure software-engineering methods like TDD do.

Getting tips from pros on how they work, and learning techniques to improve my writing and making the end-result more useful to others would be wonderful!

The How

So last Sunday I hopped onto a train to Prague and 7 hours later arrived at a wonderful pre-conference reception event at the new Apiary offices just a few blocks from my hotel (I’m getting really good at this 😉). I knew absolutely no-one there but after just a few rounds, grabbing a beer and some food, I got into a few discussions about Confluence and Sphinx. The atmosphere was extremely welcoming and not a single eyebrow was raised at me not being a technical writer 😊.

Sadly, the long travel time in an A/C’d train sitting at the sun-sided window had taken its toll and so I had to excuse myself rather early in the hope to be fit for the actual conference the next morning.

The main event took place at the Klub Lávka right below the beautiful Charles Bridge at the east bank of the Vitava river. Funny thing is that I’ve seen that restaurant many years ago during my first trip to Prague with my parents and wanted to go there. Well, now I got the chance to do that for two whole days 😊

My Takeaways

Usually, I’d now write about a couple of my favourite talks but picking favourites here would be futile and this whole post would be doomed to explode. I simply learnt so much, I guess I will just write a simple takeaway section. So, here we go:

• Glossaries can help solve a lot of issues when it comes to communicating between developers, QA, support and the client. (Emilie Boillat’s talk Whatchamacallit: Controlled Vocabularies for Technical Writers)

• It’s not just me who tries to make text more emotional by using emojis. (Sonja Heinen’s talk Visual Documentation Language)

• There is so much more you can automatically check within your documentation than just spelling. (Adam Dangoor’s talk Tested and Correct, How to Make Sure Your Documentation Keeps Working)

• I should definitely use thesauri more often. (Emilie Boillat’s talk Whatchamacallit: Controlled Vocabularies for Technical Writers)

• Focus more on guidelines than rules to not prevent people from adapting a template in order to describe something in the best way possible. ( Free Your Mind and Your Docs Will Follow by Patrick Keegan)

• Provide clear and easy to find pathways through your documentation. ( Gardening Open Docs by Florian Scholz & Jean-Yves Perrier)

• The distinction between “micro-copy” and “embedded help”. (Before the docs: writing for user interfaces by Beth Aitman)

• Interview users to build up the vocabulary of your documentation and UI elements. (Before the docs: writing for user interfaces by Beth Aitman)

• I don’t want to publish any academic papers 😉 (The quest for scientific credit for software documentation by Anna Jaruga)

• Docs should be information or teaching tools, not persuading. (from All roads might not lead to docs by Christina Elmore)

I could go on but this post is already long enough and there is still so much more to tell 😊

Feedback for the Organisers

The organisers also explicitly asked for feedback as this is still a very young conference series and there is always things that could be improved or not praised enough!

• The food in general was great but at the pre-conference reception it was simply amazing. Just ordering some takeout food is absolutely fine if it has this level of quality. I wish there were services like this in Graz!

• Big thanks for the fresh fruits during every break. So many events don’t have any and here it was nearly too much 😊

• 30 minutes per talk is just the right length. 10 minute breaks for speaker switches are perhaps a bit too long, though. For a single-track conference 5 minutes would IMHO suffice.

• The chairs were a bit too close together so taking notes with pen and paper was a bit hard.

• Oh that projector 😩

A huge thank you to all the organisers, supporters, and sponsors!

Concluding …

That’s about it. WriteTheDocs Europe 2015 was simply an amazing event with awesome people and great talks. I hope that next year’s US event will be around the time when PyCon happens so I might be able to combine these two events!

Can’t wait to meet all these fine folks again!