The Importance of Documentation

So in my experience as a developer, documentation is probably one of the most overlooked or even downright ignored things. To be fair, I understand it completely! Documenting is boring, it's slow, it's unglamorous, it often needs updating to stay relevant, it's generally not appreciated by other developers on the team... All in all, it's honestly a major pain. Compared to writing code and even writing unit tests, documenting is an unfun slog in comparison.

However, I'd argue in modern times, documentation is even more important than ever. If you have a project you intend for other people to use, you owe it to them, to your team and to yourself to write good documentation.

Why Write Documentation?

The main reason is fairly obvious: to simply explain just how to use what you've made.

Here's the thing, when someone wants to know how to use your library, the last thing they want to do is read your code. If I need to read the python code of a library to figure out how to get started, I will move on to something else. The same goes for header files, telling someone to read your header file to figure out your classes is just as bad and lazy. I don't want to have to read code for half an hour to end up determining that a library isn't a good fit for my project.

Good documentation saves time for everyone involved. Instead of your potential users needing to spend hours reading your code to figure out if your library can actually help them or not, they can just look at the documentation to see if its a good fit. From documentation, you can quickly determine the capabilities of the library and figure out how to use it in the way they need.

The other problem is the rise of AI and poor documentation only further increases its relevance. Imagine you have a complicated library like OpenCV, but it doesn't give you meaningful examples to accomplish simple goals. Previously, you'd probably Google it, go to Reddit or StackOverflow or end up on Discord to ask other developers. These days? You can just ask an AI to generate the sample code.

It's a horrible state of affairs when you come across a project so poorly explained that you need to ask an AI how a feature works or to get a starting point for your project. I don't like where this AI stuff is going, but I also value my time. When I come across a project with poor documentation, I'm not above asking Bing or ChatGPT what to do. It also never stubbornly says "Why are you trying to do X when you could do Y?", or "Have you tried Googling it?" which are major frustrations of mine.

Is it Good Enough?

I would argue the following types of documentation aren't enough to fully document how a library works:

• Header Files
• Source Code Comments
• Descriptions of classes/structs/functions in isolation

The major problems with these are that they describe things in isolation. This is great if you already have a picture in your head for using a library. If you're just trying to put some functionality together, this is useless.

Just imagine for a second that you're a fresh developer, trying to figure out a simple "hello world" program in C. Now picture that there's no examples of how to use printf and you're advised to read the man page on how it works. If you're trying to do something super niche, the man-page is great. But all the guy needs to do is printf("Hello world!\n").

This is something that bugs me quite a bit about documentation generators from comments, such as Doxygen and Rustdoc. They document functions and structs in pains-taking detail, but you don't get the full picture of how everything fits together or examples of common and not-so-common tasks for the library.

What to Do

Examples, examples, examples, examples, examples!

Build multiple common examples for your user. It's great having a simple example to get someone going off the bat, but what really helps a lot is having numerous examples showing different uses of your library. If I could give a massive shoutout to one library that absolutely does this right, it's libcurl.

Just look at all these examples accomplishing different goals. On top of that, the code is meant to be short and sweet at the expense of ignoring error checks. This is where you could use the function-by-function documentation to ensure you're using the library correctly and catching all error cases.

You can also use your unit tests as documentation to show what error conditions can happen and how to check for them. I'd argue this partially falls under the previous section and that people shouldnt have to read your code to understand how to use your library. I don't think code should only be documented by unit tests, but it's important to have them and they can potentially act as proof of concept code.

The other mechanisms I described in the previous section are also helpful. Commenting your header files and creating isolated documentation for your functions and classes are helpful, but I think examples are the primary driver for their usefulness. Examples can give someone the big picture to start using a library while the detailed documentation can help them use it right and be driven to other functionality they hadn't noticed yet.

Sigh... This was just a big rant. I wanted to emphasize how important it is to have good documentation because I hate when I come across a great project where the documentation is missing. So please, if you're releasing something for people to use, please make sure you explain what you've done and how other people can make use of it properly.