Writing proper documentation. Why is it so hard?

We've all been there, searching for a new pattern, UI element, or method. You remember seeing it before somewhere but can't quite remember where, or you've got a great idea that you can't quite realize, or you want to try out a new library. When the documentation doesn't live up to the software it's based on, it drags the whole product down.

Why does poor documentation exist?

There are many reasons we can get documentation that isn't fit for purpose. Project deadlines, developer turnover, or merely leaving documentation until it's too late all lead to poor documentation. On top of this, writing documentation can be hard because developers typically want to be coding, not copywriting. At the same time, documentation is too technical for copywriters to be able to create alone. There are lots of reasons why lousy documentation exists, but it's so critical that there's no excuse good enough not to do it. If you want your software to grow, you have to document it well.

How do you write proper documentation?

Well written documentation ultimately starts right at the beginning of the project. You need to think of how you're going to document what you do, and your goal for the documentation afterward. If you want to share it publicly, you'll probably need an external docs site, some tutorials, and some examples, but for an internal project, you might need less (or you might not). How you create the documentation is up to you. However, two popular solutions are creating a website specifically designed for documentation, or creating git a repository containing lots of well-formatted markdown files.

Content

All well-written documentation should comprise a short tutorial to get up and started with the software and a more robust set of documentation explaining and more in-depth docs showing all the options you have available, what they do, and your choices (if applicable). The best documentation shows instances when you might use these, things to know beforehand, and a few cases with expected results to help you get started. Inadequate documentation only lists functions that are available to you, but not how or why to use them. As a user, you shouldn't come away confused, so document everything you can think of and always give examples.

Navigation

When a user is reading your documentation, they only view it chronologically one time, while they are first learning how your software works. After that, they'll be jumping in and out at different points, trying to remember how things worked, but the order of this won't be logical or even predictable. So navigation should be simple and well structured to allow quick access to what is needed. Links between pages and content within the same page are needed to make finding specific elements just as easy.

Previews

While documentation can be excellent on its own, sometimes it's just not enough. People learn in different ways, and for some, reading isn't the answer. There are lots of different ways you could preview your code, and they differ depending on the software. A playground to test out what you're building without having to set up a code environment, or pre-created apps stored in a repo allowing a developer to reverse-engineer your code can be great, allowing users to see the end product before using it themselves. But don't sacrifice well-written documentation to create previews as previews enhance your documentation but can never replace it.

There's ultimately a lot to think about when writing documentation, but neglecting it is a mistake. It's as important as writing code itself, and a skill to admire among developers. If you're the only person who knows how to use your code, it's useless.