At the upcoming APIStrat conference in Portland, Taylor Barnett will explore various documentation design principles and discuss best practices.
Taylor Barnett, community engineer at Keen IO, says practice and constant iteration are key to writing good documentation. At the upcoming 2017 API Strategy & Practice Conference, taking place October 31-November 2 in Portland, Barnett will explain the different types of documentation and outline some of the best practices.
In his talk - "Things I want people to tell me about when writing documentation" - Barnett will look at how people use documentation and discuss tools and tactics to include other team members in writing documentation. Barnett explains in more depth in this edited interview.
Linux Foundation: What brought you to this conversation? Have you seen projects with bad documentation?
Taylor Barnett: Last year my teammate Maggie Yang and I led the effort to improve content and developer documentation at Keen IO. It's no secret that developers love great documentation, but many API companies aren't always equipped with the resources to have one. As a result, we all encounter a lot of bad documentation when we try to use developer tools and APIs.
Linux Foundation: There is often a documentation team, and there are developers who have written a piece of software; both are experts in their fields, but they need to be good at collaborating to produce usable documentation. How can this level of cooperation be achieved?
Barnett: In large companies this can certainly be true, although in many companies the documentation still belongs to different teams. However, there is still a need to improve the interaction. One way to improve collaboration is to write documentation early in the product development process. If you wait until everything is done and the product is ready for release, the people writing the documentation will feel disconnected from the process and see themselves as secondary. If people working on product development collaborate early on, not only does the product improve, but so does the documentation. People who write documentation usually spend some time understanding the API or tool they are writing about, so they only get better when they can work with the people who develop the product. Also, they can give more feedback from the user's point of view much sooner.
Another way to improve collaboration is to involve more people in the documentation review process. We do most of our documentation reviews on GitHub. It's great that the code is reviewed not only by someone in the role of an editor, but also by people from the engineering team and the production team. This increases the number of diversified views of the documentation and helps make it better.
Linux Foundation: How should developers approach documentation?
Barnett: Most developers are very familiar with the idea of Test Driven Development (TDD), but how familiar are they with Documentation Driven Development (DDD)? DDD steps:
- Write or update documentation,
- Get feedback on this documentation,
- Write a failure test according to this documentation (TDD),
- Write the code to pass the failure test,
- Repeat.
This can be a great way for developers to save a lot of time and not spend too much time on poorly designed features. As Isaac Schlueter, co-founder of npm, says about documentation development, "It's an effective way to increase productivity by reducing both error rate and cost." Our brains can only store a limited amount of information at once. In computer terms, our working memory is quite small. Writing down what we think about is a way to "offload a large chunk of thought without data loss," allowing us to think more slowly and carefully.
For example: At Keen IO, we recently split our JavaScript library into three different modules. This decision was inspired by the documentation we maintained. We tried to streamline the documentation, but it was too much to cover everything with limited attention. Many important details and functions were hidden in the noise. For example, if all the documentation had been written earlier, we might have made this decision earlier.
In addition, for a developer who writes documentation himself, constant repetition and practice are important. Your first version of the documentation won't be great, but by focusing on trying to write understandable text, it will get better over time. It's also important to have another person who isn't familiar with the product who can review your documentation.
Linux Foundation: if developers write documentation for other developers, how can they think like users?
Barnett:
I used to think that developers are the best people to write documentation for other developers because they are one. I still think this is partly true, because some developers have a lot of knowledge. If some time has passed since the developer has learned something, there may be a so-called "curse of knowledge". The more you know, the more you forget how it was before. That's why I love talking about empathic documentation.
You need to empathize with the user on the other end. Don't assume he knows how to do anything, give the user the resources to complete steps that you may find "easy". Also, the notion that something is "easy" or "simple" when it doesn't work for the user is the scariest feeling for the user. It makes your users doubt themselves, feel frustrated, and a bunch of other negative emotions. Always try to remember that you need to be empathetic!
Linux Foundation : How important are documentation tools?
Barnett: Very important! Earlier, I mentioned using GitHub for reviews. I'd also recommend doing ongoing integration testing on your documentation site if you're not using a service like ReadMe or Apiary to make sure you don't break it. Related topic: Are you building your own product or using a service? Tools can be helpful, but they may not always be optimal. You must find a balance based on your current resources. Finally, I would recommend trying Ann Gentle's book, Docs Like Code. She brings up the topic of tools many times in the book.
Linux Foundation: Who should attend your session?
Barnett: Everyone! I'm just joking. If you are someone in a developer role such as relationship developers, evangelists, advocates, marketers, etc., if you are on a production team as a product or platform developer, or if you are a developer or engineer who wants to write great documentation.
Linux Foundation: What is the main message of your conversation?
Barnett: Anyone can write documentation, but with some practice, iteration, and work on different writing skills, anyone can write great documentation.
Learn more in Taylor Barnett's talk at APIStrat, October 31 - November 2 in Portland, Oregon.
