3 Essential Components of Great Documentation

Eli Bierman — Wed, 13 Jun 2018 02:15:28 +0000

I originally wrote this as a response to @nonlinearnygma's post:

Article No Longer Available

It got really long and I felt a bit rude leaving such a long comment, so I decided to make it its own post. I clearly have a lot of opinions about documentation! This post focuses on what makes documentation great, and how a beginner to a project can get involved in contributing to its documentation.

Update: After writing this post I saw @ojkelly has a very similar post describing documentation in layers:

The Four Layers to Great Documentation

Owen Kelly ・ Jun 7 '18 ・ 5 min read

#documentation #docs #marketing #writing

I really love how he describes the layers building on each other, so be sure to check out that post.

But Nobody Likes Writing Docs...

If you feel this way you are not alone. Writing documentation doesn't always feel like a priority when you also need to code. Good documentation makes code more reusable and understandable, so the code and other coders will thank you for it. Writing documentation at the same time as you write code can make it a more manageable and enjoyable task.

Writing Docs Helps You

Writing documentation is a great way to think through the details of a technical subject. It can help reframe issues in your mind that lead to insights about the project or areas for improvement that you may not have thought of before. It can even help in the planning stages of a project or new feature. Some people even practice Documentation-Driven Development!

Writing Docs Helps the Community

Documentation is the first place most coders go to try out or learn about a new project, or when they come across an issue or try solving a new problem with a project they already are familiar with. That means that documentation contributions can make even more of a positive impact on a project's community than contributions to the code.

GitHub's 2017 Open Source Survey found that the biggest problem encountered in open source was "incomplete or confusing documentation." Their top insight from the survey was this:

Documentation is highly valued, frequently overlooked, and a means for establishing inclusive and accessible communities.

Any contribution (small or large) is always greatly appreciated by the project maintainers and its users.

Aspirational Documentation

Some projects with documentation that I try to learn from:

VueJS
SQLite
FreeBSD (especially compared with Linux)
Bunjil (I haven't used it, but this GraphQL server by @ojkelly that he shared in his post has really #nicedocs)
Docker (contributed by @presto412)
AWS (contributed by @technologymop)

All of these projects include the components I describe below. Let me know in the comments if there are any projects with documentation you love. I'm always looking for more documentation inspiration!

My Ideal Documentation

In my opinion the ideal documentation usually has 3 components.

The Why / Goals: the context and goals of the project
The What / API / Reference: detailed technical documentation of the programming interface
The How / Examples / Guides: example-based guides for accomplishing specific tasks

The Why / Goals

What was the motivation for this project being built in the first place?
What are some similar projects and how are they different?
What types of projects would this project be a good fit for, and when might something else be better?

Usually this is best answered by the authors of the project. If it's possible, it might be helpful to get their point of view on this to add to the documentation if it's not there already. Sometimes people leave out explaining where the project might not be the best fit, but it is very useful and appreciated by users.

The What / API / Reference

What are the different high-level components and how do they fit together?
What are the different low-level data types and functions and what do they do?

There is usually some of this already. If there isn't any, it can be very difficult to get started at all. This can be a good place for suggesting changes where things are unclear to you as you are learning how to use the project. Maintainers can sometimes be picky about this area of the documentation since it's viewed as the authoritative source of information, but it can be a good opportunity to learn about the nitty-gritty details of the project.

The format of this type of documentation is often language-specific, since most languages come with some kind of built-in system for generating docs from comments in the source code. That is usually the format that people coding in that language expect to see this type of documentation in.

The How / Examples / Guides

How do you install the project and get some basic code running?
What steps do you take to build a simple application using this project?
What steps do you take to address common problems the project addresses?

This is usually the area with the most room for improvement and easiest for someone new to the project to jump into.

This part of the documentation holds a user's hand and walks them through each step in a clear way, leading them to the nirvana of working code that solves a real issue (or it's clear how it can be applied to one).

You can write this type of documentation by building a small thing using the project and take careful notes at every step about what you're doing, so that somebody else could follow along by just copy-pasting. You can easily turn this into a guide that takes users from total beginner to a small win and an aha-moment.

Most people coming to a project are total beginners in it, so writing for other beginners from a beginner's perspective is immensely valuable. People with more experience in the project may actually have trouble seeing from a beginner's perspective so they usually really appreciate this type of contribution. I think this type of documentation goes a long way in making projects more approachable.

I'd love to read other people's opinions on what makes good documentation here or on @nonlinearnygma's post. Do you have a love-hate relationship with documentation? Any favorite #nicedocs?

DEV Community: Eli Bierman