Move fast and document things

Ann Johnson

Last month, I attended the Write the Docs conference in Portland. Write the Docs was founded with the goal of building a community of people who care about documentation. Or as they put it:

“We consider everyone who cares about communication, documentation, and their users to be a member of our community. This can be programmers, tech writers, customer support, marketers, and anyone else who wants people to have great experiences with software.”

The Write the Docs founders call these people documentarians. I’m a technical writer, but I like this conference because I get to meet and share ideas with people with different backgrounds who share a common goal - create great docs that are useful and informative. This leads to a lot of interesting discussions about how we can provide better documentation, and even what “better documentation” means. This year I submitted a talk proposal and was lucky enough to have it accepted. About 400 people attend the conference, and it features a main talk track in the main room, and then a separate set of “unconferences” in a separate room.

You can find recordings of all of the presentations on YouTube. You don’t need to be a technical writer to find these worthwhile; one of the great benefits of Write the Docs is hearing presentations on documentation tools, processes, and culture from engineers who bring different perspectives and challenge some of my assumptions about documentation.

I had three key takeaways from the conference:

  • We should focus on documenting what the user is doing, not what the application is doing
  • Consider Just-in-Time documentation (document what your customer needs to know right now) vs. Just-in-Case documentation (document everything that your product can do, every screen, every UI field, etc.)
  • Good internal communication (like we have here at Interana) is rare, valuable, and results in better docs

And the most important point: “Docs are better when written with a team.”

The conference takes place over two days, but there are two additional days of pre-conference activities. During one of the pre-conference prep days, there was a “writing sprint” (just like dev sprints involve coding, people brought documentation projects they were working on), as well as workshops about API documentation. The API discussions were of particular interest to me, as Interana is releasing our new Query API.

The “real” conference days began with a quick breakfast, a tasty chocolate doughnut from Blue Star, and then some panicky rehearsal of the talk I was about to give. I talked about how documentation and customer support teams can work together to create awesome documentation. My talk went by in a blur, but I got a lot of great feedback and requests to have an unconference discussion about the topic. A big theme of the conference is collaboration.

Building a collaborative documentation culture is my primary goal at Interana, and I’m working on turning that into a reality in the near future. The Write the Docs conference allowed me to talk through these ideas with other documentarians, learn about what worked (and didn’t work) for them, and gave me encouragement that this is a worthwhile goal that will result in more complete and more usable documentation that meets our customers’ needs.

I look forward to sharing the results with you in future newsletters!

Previous article Blog Summary Next article