Introduction

It’s one of the most important things in software engineering: Good documentation.

Some people love it, some people hate it, but there is no denying its importance. This is true for all projects: internal tools, open source projects, and closed-source libraries with a public API.

In this post I talk about three different kinds of documentation and why all of them are important:

  • user documentation
  • admin documentation
  • architectural documentation

This is an observation from my own work and certainly not an absolute truth.

The underlying theme is to think about your audience to tailor your documentation to create the most value for them.

How to think about documentation

Documentation is of utmost importance for any serious project. It not only helps you remember what you did 6 months ago but also helps others to understand how to use your project. From a business perspective, it drives user adoption and makes it easier to find contributors.

Good documentation is hard. It’s repetitive. It’s a lot of effort to maintain. Often, it’s not valued by stakeholders.

Besides, this should go without saying: Keep your documentation up-to-date. Wrong documentation is even more frustrating then no documentation.

Generally, there are two classes of projects: libraries and applications. Even though the nature of their docs might be different I would argue that both have similar requirements.

In commercial settings I believe good documentation is actually great marketing as well, especially for developers who are notoriously hard to sell to. That does explicitely not mean to try to sell your services in your docs. It’s more a change of perspective to underline the importance of documentation.

The most important: End-user documentation

The target audience for the first type of docs is the end user. It is the most important one and almost every project has one, no matter how small it is.

It answers central questions for the user:

  • How do I get a minimum example running?
  • How do I install it?
  • What’s the basic functionality of the library?
  • How do I make use of the things the project as to offer?
  • Which use cases are typical and how do I implement that?
  • What are more advanced features and how do I use them?
  • …
  • API reference

Everything that an end user might want to know goes in here. This includes the purpose of the library and what problem it’s intending to solve. This is something most docs are really bad at. Too often I have seen documentations that start with highly technical details instead of a top level explanation of its purpose.

One of the things I am looking for in docs is the time to value. I want to have a success as soon as possible. Most libraries actually can achieve that with little code. This is often overlooked but really important, because when users understand how to use something and have a quick success they will be more likely to stick with you.

Some self-reflection

Something that I found interesting in past projects is the fact that almost all readers went straight to the examples. This was partially due to the unclear value proposition and people wanted to see what you can do with the library.

However, it made me reflect on my own behavior and I think that’s exactly what I do in most cases. I want to see what the code looks like in a realistic scenario and examples usually give me the best sense of that. Understanding how users read your documentation is helpful to deliver higher value.

Ehm … Who is the end user?

So, one question remains. Who is the end user? This is something you should be able to answer, otherwise you don’t know your audience well enough.

For a library project your end-users are definitely other developers. It’s usually the easiest group to talk to, because your speak their language.

For applications, no matter if it is a GUI app, web app or a command line tool, your audience can be anyone. Highly technical users or people who don’t know a lot about technology at all. Writing documentation for applications is much harder and you need to be even more aware of the nature of your audience.

No matter who your audience is, providing a path to a quick success is important. The more technical your project is, the more important are quick wins.

The painful: Admin & maintenance

This type is all about the installation, administration, and maintenance of the project. This might have significant overlap with the user documentation but it’s still important to mention it here.

Especially, if your project is geared towards business users it’s important to provide this. Developers are often not the ones managing the infrastructure. The ones in charge of maintaining development and production environments don’t care about your API but about the ways to install it, to update it and what else to consider.

Therefore, having a dedicated documentation for this is good to have.

Unfortunately, this is a painful part to think and write about. Why? Because it requires you to deal with packaging, deployment, and the plethora of different systems. Depending on your project even just writing 3 sections about the installation on Windows, MacOS, and Linux is some serious work.

This gets only amplified the more in detailed your instruction are:

  • dealing with different operating systems
  • cloud vs. on-prem deployment
  • different cloud service providers
  • how about package managers? System-wide ones or language-specific ones?
  • …

This is something that can grow over time. It constantly has to be revisited because things that are not under your control might change e.g., how something is deployed to a cloud service provider.

For contributors: Architectural documentation

Documenting the architecture of your project is important for yourself, other developers, and new hires, too. It becomes much easier to contribute to a project if the overall structure and architecture is clear. I don’t always need the details but having a mental model of how things work together makes it much easier to contribute.

I believe it’s not just about documenting the architecture but also about providing a reasoning for the decisions made along the way.

  • Why did you decide to go serverless instead of an EC2 instances?
  • Why choose this specific type of database?
  • Which trade-offs were considered?

You get the idea. Again, this does not have to be highly detailed but having a few bullet-points might help everyone down the road.

This type of documentation might be publicly available or kept private. That depends on your project. One of the main advantage is that your on-boarding process for new developers will go much more smoothly and there is always a reference to go to first, before ask someone else. With remote work, this just becomes more important.

What else to consider

  • Great documentation is obviously great, but there has to be an obvious path to reach it, too. It has to be discoverable in order to provide any value to your users. There should be a prominent link to your docs. Your documentation should also be the first result in any Google search for docs of your project.

  • Most documentation tools create static website that can easily be hosted on GitHub Pages. You can connect it with your domain or any sub-domain and have a professional documentation page. Make sure to backlink to your actual website, if you have one.

  • Consider some analytics. It doesn’t have to be highly specific but it’s helpful to get an understanding of the parts that people look at and which they might not look at at all. This way you can concentrate your efforts on the relevant parts to make it even more useful for the reader.

Closing Thoughts

We covered three different types of documentation. The key message is to write for a specific audience.

There is overlap between different audiences and that’s not always easy to deal with but the effort is worth it in the end. Writing good documentation should be a priority for all projects, especially if you want to grow a user base or even make money with it.

I always found documentation to be an incredibly rewarding part of my work. It’s often the first interaction a user has before trying your library. It empowers people to use whatever you have created.

I am open to do contracting as a backend software and data engineer. I like to automate processes. I like technical writing. Check out how we can work together.