The Sacred Steps to Achieving Good Documentation

So, you've spent hours, weeks, or even months on a project you believe in, and you are damn proud of it. It is capable of solving problems every developer faces, the test coverage is about 110%, and the code itself is just shy of a work of art. But then, as you push your last commit, you remember that, lurking in the shadows of your IDE, was a holdup most developers underestimate: documentation.

Ok, maybe it is not as scary as I make it sound, but still something you should respect, after all, every programmer has, at some point in their life, come across a poorly documented library or package, spent a few minutes of guesswork trying to make it work, maybe even tried reading a bit of the source code, just to finally give up on using it. Turns out, most of the time, an undocumented application is a barely usable application. Be it an API, a smartphone or a car, nobody wants to learn how to assemble an engine in order to drive back home.

That being said, the importance of documenting your application is no breaking news. What might be surprising, however, is how difficult and time consuming the process of creating such documentation can be. While writing the documentation on my open-source software Meta-System, I came across a few difficulties that I would like to share, so that maybe you can avoid them yourself. But where do you start?

Picking the Right Tools

The first big challenge you might face is which platform to use for your docs. Some simple projects just use the github wiki as a way to serve the documentation, which works well for simpler things, but the reality is that, for medium to large projects, such tools are far from being enough, so you'll probably have to resort to some other options such as Apiary, Read the Docs or even a combination of tools, such as Github Pages and Docussaurus, which was what we used for Meta-System.

But Which One Should You Choose?

Of course, the correct tool, as usual, depends on the requirements of your project. For an API, Apiary might be your best choice, if you want a more generalized documentation you Read the Docs might give you a quick and free way to have your documentation up and running, however if you really want a lot more control over styling and such, docussaurus can really help. There is also a last option which is quite rare though: just make a static website from the ground up. You can use React, Svelte, or really anything you want to build a documentation site. It's a lot more work than any of the previous options, but if you truly believe you need to control every single aspect  of your documentation it is still a possibility.

A Final Advice

In the end it is very much a decision about how much you want/need to customize your docs. The more "pre-made" it is, the easier it will be to start writing your docs. The more "customizable" it is, the more you'll need to do in order to get everything up and running. To summarize, my final advice would be: choose the tool that fits your necessities without being a production barrier.

After all is set, you can start typing away! Though, that might be as much fun as you expect...

Not a Great Netflix Series

You might be a gamer, or maybe a tv shows aficionado, or you just love the musical expression of Bach; either way, there is something you find deeply entertaining, that could have you enjoying it for hours unnoticed; writing documentation certainly is not one of those things. To put it simply, writing a documentation can be quite boring. Not only is it a very repetitive task, but it is often quite time consuming and, although there is no way around that specifically, there are ways to make it less disheartening.

Organize Your Workflow

The first thing I found out truly helped me was organization: separate all the docs you'll be writing into related groups, not only does this make it easier to manage the files involved, but you can also keep your train of thought: instead of constantly jumping between the multiple subjects your documentation approaches, you can focus on one at a time, making it easier to write the individual entries.

Prettify It

You should also try making your docs section more interesting: add tables, text formatting, syntax highlighting, maybe even a few images. There is a good chance that if writing your documentation is boring, so will be the reading. However, there is no need to overdo it as well, after all we are trying to write a technical documentation, just make sure it is not a long text wall.

If you follow all that, you'll have an infallible documentation, though you might still stumble across a very special type of PEBCAK, one I usually call...

The Teacher's Paradox

In my opinion writing docs is quite akin to teaching, and therefore it also holds a similar problem: whenever you are trying to teach someone, you will need to know two things: the topic you are about to teach and what the student doesn't know, and the last one is quite a challenge. After all, how do you know what you don't know?... Now, let's not get too Socratic about it; the point is: it's difficult to put yourself in the place of someone who does not know about the topic since you already do, and that makes the process of teaching (or documenting in this case) slightly troublesome. In order to minimize such problems, I'd recommend keeping a few things in mind:

You Can't Know What They Don't

Do not expect the reader to have any previous knowledge. There is no way to know if your user got to a section following your docs topics, if they are coming from one of your tutorials or from an external link. Therefore you can't be certain they already know something they should. The best way to solve this is to simply make sure to provide every link possible. If there is an inhouse term you use to specify something, make sure to link to a section explaining it whenever it appears. A concept required for further understanding of the docs? Link it. A program or lib required for your software to work? Link it. There is no way to know what your reader doesn't, but there is a way to make sure they are not lost when that inevitably happens.

The More Generalist the Better

Always try to provide multiple approaches for learning about your software. Some people will be more pleased to see a text describing the intrinsics of the code or how it is expected to work; others just want a few quick examples to understand the basics of what to expect from a certain situation. Whether you are one or the other, make sure to provide both a good text as well as good examples. Examples are always a nice way to solve misunderstandings that might have arised in the text, while plain text is really the only good way to explain something in a completely generic way.

After all that you probably have a full documentation page that contains all your software info in an intelligible way, without being too overwhelming or boring. Maybe you achieved all that without using some of the techniques mentioned here. So tell us, what was your experience writing your documentation? Which tools did you use that you regret and which ones saved your life and sanity?