2018 marked the sixth year of Write the Docs Portland conference, which is an event targeted solely at documentarians.
Originally starting life as a conference just for developer documentation, the conference has expanded to include anyone with an interest in documentation.
Write the Docs has expanded to become a global conference with regular meetups throughout the year.
Low-down on Write the Docs conference
The single most compelling feature of this conference is just what an inclusive environment the organizers have managed to create.
This culture is often fostered using documentation as a tool. For example, clearly labelling all the entrances or putting up other signs.
Things like this:
This also encompasses labeling the different foods, giving everyone their own name badges to customize with stickers, along with the Pac-Man rule.
The Pac-Man rule and inclusivity
What is the Pac-Man rule, you say?
Pioneered by co-founder Eric Holscher, the Pac-Man rule means:
“When standing as a group of people, always leave room for 1 person to join your group.”
This means you have to stand in a Pac-Man shape so that new people are always able to enter the group.
There are also many, many helpful posts in the Write the Doc’s Slack during the conference, where attendees can also arrange social events and find answers to any questions they have.
Summary of the conference
Aside from the two days’ worth of talks, there is also a hike on the Saturday upwards along one of Portland’s beautiful trails. This is two hours of walking, sweating and talking to dozens of new people who will later be attending the conference.
Then, Writing Day on the Sunday involves participating in a variety of open source projects during a ‘sprint’.
Projects involve contributing to Write the Docs’ own website, to CockroachDB docs, or submitting your own project. Each project is usually a form of open source documentation, and this day is a great opportunity to make your first foray into open source.
On top of the official Monday-night social, attendees frequently go out to dinner or for drinks together with new friends. The time surrounding the conference is jam-packed with social activities, and this is great because Portland has lots to do and the local people are very friendly.
The conference has a brilliant Code of Conduct for other communities to learn from if they want help in creating an inclusive community.
All the talks are accessible to specialist and lay audiences, with accessible live captions broadcast during the entire conference. Anyone can learn something from each talk but there are also deeper nuggets of wisdom to be gained.
‘Empathy’ was a key theme running through many of the talks, and the importance of being able to put yourself in your users’ shoes – whether that’s an end user, developer, or an internal colleague.
Kat King, Empathy-driven developer docs
Technical Writer at Twilio, Kat King talked about building empathy-driven developer documentation. We are all frequently guilty of lacking empathy for developers, especially when becoming the recipient of some less than thoughtful community comments from developers.
Some of these comments can be really hurtful, especially after you’ve invested so much time and effort trying to create good docs. This can lead to negative reactions and a nagging feeling of depression and despair.
The answer to this challenge is actively working with your developer users to find out what you can do better. Kat found that, after reaching out to one developer who left a disparaging comment, the developer was surprised to discover that humans actually read the comments.
Erin McKean, What Writing Dictionaries Taught Me About Writing Documentation (And What I Had to Unlearn)
Developer Advocate at IBM, Erin Mckean gave a fascinating talk on her work with dictionaries how this has influenced her approach to documentation.
Erin has gone from a long career in writing dictionaries and other reference books to becoming a full-time software developer. This has given her a unique insight into how to write documentation for software.
Erin has also founded a fascinating project called Wordnik which aims to reinvent the dictionary. Instead of beginning with a priori definitions of words, it embraces how language is evolving. Words mean what we want them to mean.
Wordnik definitions bring words to life by positioning them in context and facilitating word discovery. The site takes suggestions from users for definitions of words.
Larry Ullmann, Making Your Code Examples Shine
Technical Writer Larry Ullmann from Stripe gave a talk on just how they make their code samples so awesome at Stripe. Stripe has led the way with developer documentation and this has resulted in a new gold standard.
On the other hand, it can be difficult to maintain such a large number of code snippets. Users must be able to copy and paste each one successfully as a working example. This number of examples is only growing as Stripe expands operations, and each example must also work in eight different programming languages.
For Stripe, the answer does boil down to creating your own tool to automatically generate and update code samples, which may not always be possible for everyone. Follow a style guide for your code to make examples easier to understand.
We’ve written a whole post on just how much we like the Stripe documentation.
Bob Watson, Audience, Market, Product: Tips for strategic API documentation planning
Another brilliant talk by Bob Watson, Assistant Professor of Technical Communication in the Engineering School at Mercer University, involved the importance of marketing your API docs properly – and this means knowing your audience. There are several different types of developers who will respond to different kinds of documentation, and tackle problems differently.
Understand your API’s audience, market and product. No API documentation can be produced in a silo – but sometimes this is easier said than done.
Overviews, tutorials, how-tos, and references are various types of documentation. An overview will attract developers to your API, while Hello
World documentation functions as a demo. Copy-and-paste-coders will respond better to working code examples, while conceptual documentation will appeal to deep learners.
The audience, market, and product is not static so documentation needs will change over time.
All the talks were fantastic and this is just a selection of highlights. You can find the full videos of every talk on the Write the Doc’s YouTube channel.
The conference is incredibly welcoming to new speakers and a few people were public speaking for the first or second time ever. A great opportunity to flex your public speaking muscles is also the lightning talks, which are 5-minute talks on every topic.
For example, someone spoke about accessibility, while another spoke about ‘DocsOps’, and another talked about how it’s okay to sometimes say no. One speaker even played the tuba.
The job fair
As this is a conference, people are there not only to learn and network, but also to be on the lookout for new job opportunities. Many attendees have yet to even find their first technical writing role.
Write the Docs 2018 trialled a job fair downstairs where the some of the sponsors were able to have their own booths. Attendees came up to company representatives to find out more about current job opportunities and ask questions.
The sponsors for Write the Docs include companies like Google, Mozilla, and Twilio, as well as ourselves – Document360. So as a technical writer, you can attend the conference to learn more about your craft, and also find a potential new job opportunity.
If you’re building up the courage to go to a conference for the first time, Write the Docs should be the one you start with. You’ll learn lots, make new friends and have a great time.
If this conference suffers from one flaw, it’s that there are too many exciting things to do and you won’t be able to do it all. That’s all the more reason to sign up for next year’s conference.
There are also further Write the Doc’s conferences this year scheduled in Cincinnati, Australia, and Prague.
We are very proud to sponsor this amazing conference and look forward to doing it again next year.
Document360 knowledge base software for SaaS companies is currently in beta. Sign up for your free trial now.