Secrets of Writing Good Documentation

At the upcoming APIStrat conference in Portland, Taylor Barnett will explore various documentation design principles and discuss best practices.

Taylor Barnett, a Community Engineer at Keen IO, says practice and constant iteration are key to writing good documentation.  At the upcoming API Strategy & Practice Conference 2017, Oct. 31 -Nov. 2 in Portland, OR, Barnett will explain the different types of docs and describe some best practices.

In her talk — Things I Wish People Told Me About Writing Docs — Barnett will look at how people consume documentation and discuss tools and tactics to enable other team members to write documentation.  Barnett explains more in this edited interview.

The Linux Foundation: What led you to this talk? Have you encountered projects with bad documentation?

Taylor Barnett: For the last year, my teammate, Maggie Jan, and I have been leading work to improve the developer content and documentation experience at Keen IO. It’s no secret that developers love excellent documentation, but many API companies aren’t always equipped with the resources to make that happen. As a result of this, we all come across a lot of bad documentation when you are trying to use developer tools and APIs.

The Linux Foundation: Often, there is a team of documentation writers and there are developers who wrote that piece of software; both are experts in their own fields, but they need a lot of collaboration to create usable docs. How can that collaboration be improved?

Barnett: In large companies, this can definitely be true, although in many companies documentation is still owned by various teams. The need for more collaboration still applies, though. One way to improve collaboration is bringing docs into the product development process early on. If you wait until everything is done and going to be released soon, people writing documentation are going to feel left out of the process and like an afterthought. If people working on the product development collaborate early on, not only does the product become better, but so does the documentation. People who are writing documentation usually spend some time figuring out the API or tool they are writing about, so they only get better when they can work with the people doing product development early on. Also, they can give great feedback from a user’s perspective much earlier in the process.

Another way to improve collaboration is to bring more people into the documentation review process. We do most of our documentation reviews in GitHub. It’s great to not only have someone in the role of an editor review it but also people from the Engineering or Product teams. It increases the number of eyes on the docs and helps make them better.

The Linux Foundation: How should developers approach documentation?

Barnett: Most developers are pretty familiar with the idea of Test Driven Development (TDD), but how familiar are they with Documentation Driven Development (DDD)? The flow for DDD is:

1. Write or update documentation,
2. Get feedback on that documentation,
3. Write a failing test according to that documentation (TDD),
4. Write code to pass the failing test,
5. Repeat.

It can be an excellent way for developers to save a lot of time and prevent spending too much time on poorly designed features. As Isaac Schlueter, co-founder of npm, says about Documentation Driven Development, writing clear prose is an “effective way to increase productivity by reducing both the frequency and cost of mistakes.” Our brains can only hold so much information at once. In computer terms, our working memory size is pretty small. Writing down some of the information we are thinking about is a way to “off-load significant chunks of thought with hardly any data-loss,” while allowing us to think slower and more carefully.

For example: At Keen IO, we recently split our JavaScript library into three different modules. This decision was inspired by the documentation we were maintaining. We had tried to streamline the docs, but there was just too much to cover in an attention-constrained world. Many important details and features were hidden in the noise. For example, if all of the documentation was written sooner, we may have made this decision sooner.

Also, as a developer who is writing docs myself, constant iteration and practice are important. Your first version of the docs aren’t going to be great, but with focusing on trying to write clear prose, they will get better with time. Also, having another person who is not familiar with the product and can step through the documentation to review it is essential.

The Linux Foundation: If developers are writing documentation for other developers, how can they really think as the users?

Barnett: I used to think that developers are the best people to write docs for other developers because they are one of them. While I still believe this is partially true, some developers also assume a lot of knowledge. If it has been a while since a developer has done something, the “curse of knowledge” can exist. The more you know, the more you forget what it was like before. That’s why I like to talk about empathic documentation.

You need to empathize with the user on the other end. Don’t assume they know how to do something and give resources to fill in the steps that might seem “easy” to you. Also, hearing that something is “easy” or “simple” when something is not working on the user’s’ end is the worst feeling. It makes your users doubt themselves, feel frustrated, and a bunch of other negative emotions. Always try to remember you need to be empathetic!

The Linux Foundation: What’s the importance of tools in creating documentation?

Barnett: Very important! Earlier I mentioned using GitHub for reviews. I also would recommend having some continuous integration testing in place for your documentation site if you aren’t using a service like ReadMe or Apiary to make sure you don’t break it. A related topic is, do you build your own thing or use a service? Tools can be helpful, but they might not always be the best fit. You have to find a balance based on your current resources. Lastly, I would recommend checking out Anne Gentle’s book, Docs Like Code. She brings up tools a lot in the book.

The Linux Foundation: Who should attend your session?

Barnett: Everyone! Just kidding (kind of). If you are in any role that is developer facing like developer relations, evangelists, advocates, marketers, etc., if you are on a Product team for a developer focused product or platform, or if you are a developer or engineer who wants to write better docs.

The Linux Foundation: What is the main takeaway from your talk?

Barnett: Anyone can write docs, but with some practice, iteration, and working on different documentation writing skills anyone can write better docs.

Learn more in Taylor Barnett’s talk at the APIStrat conference coming up Oct. 31 – Nov. 2 in Portland, Oregon.