Why is writing documentation 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.

You can have the smartest plugins or scripts but when the docmentation doesn't provide a clear picture, you're preventing your users from getting what they want.

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.

Writing documentation is hard because developers aren't writers, and you need to be able to do both to write good documentation.

Documentation is too technical for copywriters to be able to create alone. There are lots of reasons why lousy documentation exists, but it's such a critical component that there's no excuse good enough not to do it. If you want your software to grow, open source or not, 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. Two popular solutions are documentation websites, or markdown files.

Content

All well-written documentation should contain 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).

Jumping straight into in depth API docs is a good way to confuse your users. Easing them in with some smaller examples gives them an understanding of how you approach your code.

The best documentation shows examples and any caveats to be aware of to help you get started. Inadequate documentation often skips the examples and can expect you to absorb too much information too quickly. As a user, you shouldn't come away confused.

Navigation

When a user is reading your documentation, they only view it chronologically the first time. 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 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.

Don't sacrifice well-written documentation to create previews. They're helpful, but can't replace proper documentation

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.