Tips and Top Presentations from Write the Docs Portland 2017

Three tips for writing better documentation and four recommended talks from the conference.

Ingrid ToweyImagine a room full of smart, funny, and quirky people who all love documentation, technology, and... food. Put all that together and you have Write the Docs (WTD) in Portland—a community conference where documentarians meet to discuss the things we love the most.

A direct descendant of Read the Docs

WTD is a direct descendant of Read the Docs, a site that hosts documentation of open source software. Because of its origin in the open source movement, WTD is open to a variety of job titles who all care about documentation and clear communication. This year, we had QA people, librarians, software developers, and, of course, technical writers and editors, with some User eXperience (UX) people thrown in for good measure.

Last year was my first year attending the conference, and I felt as if I had just walked into a room full of my closest friends. It was a shock to be that comfortable somewhere that quickly. A lot of that comfort is because of the conference's Pac-Man rule: If you're standing in a group of people, always leave room in your circle for one more person to jump in. Stand like a Pac-Man, ready to invite a new friend to join and be welcomed.

What happened at WTD Portland 2017

Writing docs like code

The buzzphrase of the 2017 conference was writing docs like code. What does that actually mean? It's a combination of things—partly it means using Git repositories or similar code management systems to handle and format your raw text; it also means, that in an ideal world, if you're writing docs like code, the docs and the code exist in the same repositories. Both developers and professional writers can easily improve and contribute to the documentation so that there's no barrier between the two worlds.

As Jodie Putrino said in her talk, Treating Documentation like Code: A Practical Account: "We're all doc writers now."

3 tips for writing better technical documentation

At WTD Portland 2017, we also heard a lot about how we can improve our documentation. Here are three big tips:

• Use technical writing techniques like minimalism and task analysis to make your docs clearer and better.
• Strengthen your relationship with your support people to improve your docs and their lives.
• Be aware of your readers and write for them.

In this last vein, Caring Systems: Documentation as Care, by Amelia Abreu, touched on two of my favorite topics, ethnographic user interviews and usability testing. As an anthropologist and experienced User eXperience (UX) consultant, I cannot recommend these two techniques enough!

4 recommended presentations

Check all of the amazing presentations by heading over to the Write the Docs 2017 channel on YouTube. A few of my favorites are:

• Error Messages: Being Humble, Human, and Helpful by Kate Voss. She explains how to tailor your error messages so that they are thoughtful and genuinely useful.
• Even Naming This Talk is Hard by Ruthie BenDor. She gives examples of several Terrible, Horrible, No Good, Very Bad names encountered during her career as an engineer and talks about how we can improve our naming.
• Start With the Tasks, Not the Endpoints by Sarah Hersh. She presents a case study of the process of creating task-oriented API documentation by interviewing customers and doing surveys, and ends with iterating the documentation designs.
• The Wisdom of Crowds: Crowdsourcing Minimalism in an Open Organization by me. My department at Red Hat is crowdsourcing writing critiques as a way to evangelize new documentation methods. My talk describes our approach and explains both crowdsourcing and minimalism.

Applause for fabulous volunteers

This year I presented and had to deal with technical difficulties, and yet the way that the WTD volunteers came together to make my presentation work was phenomenal. They sacrificed themselves to make my presentation possible. Nik Blanchet, the conference emcee, spent the majority of my talk on his knees bending like a contortionist to advance my slides for me. What an amazing group of people!