Your documentation is a product too

It’s a strange thing, product documentation. Everyone agrees that it’s important, and yet it’s often seen as a chore that no one wants to do. In smaller teams – and especially in startups, where getting the product ready and on par with competitors is the prime directive – people often focus on new features. For a developer product, though, where users need to be able to integrate your product into their own code bases, documentation is crucial.

When I joined Unleash, we were getting a lot of feedback saying our docs were lacking: That users couldn’t find what they were looking for, that features and configuration options weren’t documented, and that the docs were misleading or even plain wrong.

Now, six months later, most of that feedback is gone. This post outlines what I consider to be some of the most important steps we took to address the documentation issue. But while we have made some good strides toward improving the docs, we’re not done yet. There’s still lots of work to do and we keep working on it every day. But with sustained internal effort and the help of our users and outside contributors, we’re steadily improving.

Treating the documentation as a product

As an open-source company we’re all about transparency and sharing what we know. Part of that is also about learning from others in areas where we can improve. Thankfully, we’ve got a few connections that can help us in those areas.

Right about when I started, I had a meeting with Dan McKinney over at Cloudsmith (who have received a lot of praise for their documentation). A very nice meeting in many regards, the most important thing I took away from it was Cloudsmith’s attitude towards documentation: treat your docs as a product.

Treating the docs as a product means that you need to prioritize and work on the documentation just as you would any other part of the product: The docs can’t just be a byproduct of some other product. They need actual love.

It also means that if you get a user asking a question because they haven’t found what they’re looking for in the docs, then you have a bug. Yup, documentation bugs. They’re a thing now. And as with software bugs: if someone discovers a bug, you create a ticket to fix it. That way you can prioritize the issue, log duplicates, and treat it as any other bug.

If this comes off as strange, ask yourself this one question: who knows what the documentation is missing better than the users, better than the people who can’t find what they’re looking for? And by taking user input in this way, they actually prioritize it for you! If you work on things people ask about, then you know that you’re working on things people are using.

Adopting Diátaxis

As with so many other things, there’s no right or wrong way to organize your documentation. But certain ideas do have more merit than others. After looking around a bit, I stumbled upon Daniele Procida‘s Diátaxis framework.

Diátaxis provides you with 4 distinct kinds (or modes) of documentation and gives you guidelines on how to tell them apart and how to write for them.

We used this framework to restructure our documentation from vague categories such as “user guide” and “advanced” into more clearly labeled “reference guides”, “tutorials”, “how-tos”, and “topic discussions”.

In addition to just organization, the Diátaxis framework also provides you with clear guidelines for how to write for each of the documentation kinds. In particular, it expressly tells you what not to write. This has helped us tremendously in avoiding duplication between related topics, which means updates get a lot easier to manage.

What’s next?

We can’t just stand still. We gotta keep moving and improving. If you want your product to be the best, you better make sure the documentation is up to the task! In addition to keeping everything up to date and documenting new features as they arrive, we also have lots of plans and ideas that we’d like to see come to fruition:

• Now that we’ve (almost) got full OpenAPI support for our APIs, I’d love to see that become integrated into the documentation. I don’t know if you’ve tried, but writing API reference documentation out by hand? Now that is a chore.
• Some of the best developer docs out there provide you with ready-to-copy code samples complete with variables that are correct for your use case. As we don’t require any sort of authentication for the docs, we can’t just grab your details from anywhere, but we can let you enter them yourself and update code samples accordingly.

If you’ve got any ideas or other input, we would of course love to hear it! Please don’t hesitate to reach out to us.