The art of documentation for open source projects – talk at KubeCon
This week I’m attending the KubeCon conference in Seattle. The conference’s full name is KubeCon + CloudNativeCon North America 2018. I’m taking notes from some of the sessions I attend. Any mistakes in these notes are my own, and all credit goes to the presenters.
Ben Hall‘s talk was about how important documentation is to open source projects, and the changes communities can make to improve their documentation.
This statement from Ben’s introduction rings true with me:
While many open source projects have amazing code bases, the documentation is letting them down and as a result they are losing influence and opportunities for adoption and feedback.
I’ve worked on the docs for a few open source projects, and it’s hard. 🙂
Here’s what Ben talked about:
- Where docs fit into the user journey
- How docs support users
- Examples and inspiration for docs
These are the types of people who use the docs: potential users (people who’ve heard about the project and are interested in starting to use it), implementers, maintainers, and contributors.
There are a few myths about docs, including that no-one reads, and definitely no-one wants to write docs, yet the docs must exist. Ben says to address this type of thinking, we need to analyse the types of documentation people need, what they want to read. For example, avoid large blocks of text. No-one wants to read them, and writing them is hard.
Docs for new users
Consider how people approach the docs:
- The commitment pattern is very rare – this is where the reader sits down and reads the entire text from top to bottom.
- The layer-cake pattern is more common – people scan for headings and for things that are interesting to them.
- The spotted pattern is where people look for specific items e.g. a specific guide. This is also common, especially when people have used the product before.
Someone starting with the project may ask themselves: Does this project solve my problem, and will it help me with my career? Note that the README will probably be the first doc a person reads. So pay attention to it, and make sure it gives people a good overview and signposts to where to go next.
Avoid saying something is simple, or tell them to just deploy using x. Rather, showcase the project in the smallest amount of time, to help them decide whether the project is right for them. Examples are the best way of doing this. (Short videos and GIFs are often used too, but people have to download and watch them, which may be discouraging.)
Kubernetes, for example, has an interactive element in the website which gives people a feel for the project. Stripe found a significant advantage when they included interactive snippets in their website. Realistic blocks of code where you can see the core aspects of the product working.
A good tip is to include snippets of code in the docs, and link directly to GitHub for people who want to see the rest of the code.
We also need to make docs inclusive. Take care with the examples we use. Respect the fact that not everyone’s first language is English. Don’t use words like “it’s simple” or “just do this”, because for many people it’s not simple. Avoid making the user feel bad. The problem is ours, we need to make the software as simple as possible, and the docs should acknowledge that.
Docs for an active user
Active users of the project have needs that differ from those of new starters. They want to solve other problems, or find a solution for something that’s broken.
We need to focus on how people can find what they’re looking for. Discoverability in the docs. Ben gave the example of the Twilio docs, which ask readers a few questions before deciding where to take them.
If something is broken, consider the user’s emotional state at this time. They probably don’t want to read a lot of text at this time. StackOverflow and GitHub Issues have become key resources for this type of use case. When writing our docs, we need to acknowledge these resources. For example, point people to an issue and make sure the issue is informative.
Docs for community contributors
We must make sure there are good contributor guidelines. Make sure people feel safe, by including a code of conduct. Include a licence so people know the terms under which they’re contributing.
Consider running a doc sprint where contributors can come and talk to project maintainers about becoming a maintainer themselves. Also working groups and contributor summits have huge impacts on showing people how they can improve their contributions to projects.
Three key points from Ben
Developers experiment. The docs should support this mindset.
Users get into trouble. Make sure we provide doc types that support the fact that people encounter problems.
We should encourage contributions. Not only the code base should be open source, but also the documentation.
From Ben: Having amazing documentation becomes your key differentiator.
From me: Thanks for a great talk, Ben, and +1 to fostering amazing docs for amazing open source projects.