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.
Top comments (2)
Documentation has to be reflex.
Me? I hate having to answer the same question twice. I generally try to document as I go. When I'm done with a project, I like to think that there's no excuse for asking me questions, least of all the same question more than once (if I reply "what was unclear about what I wrote" and the asker's response to that is "oh, I didn't read it," I usually tell them, "come back to me when you've read it and tell me where the documentation's deficient: I'll fix it".
Similarly, I'm typically matrixed across a minimum of two projects any given week. I may be "temporarily" pulled off one project for as little as a few hours to as much as a few months. If I don't document as I go, there's no chance in hell that I'm going to be able to come back from a multi-day/week/month break and pick up where I left off.
In short, I write for me. And, if you want others to write, you need to figure out how to make them see that documenting's an effort that benefits them.
I write ERP software integrations (and such) for a fairly large utility and have been doing it for about 25 years. I write the documentation at the end of a 'project' and find it's an extremely useful way for me to review what I did and have it completely fresh in my mind when I hand [the app] over to it's ... requester. I go way over the top using Word and tables and all of that crap (that most developers hate to deal with) because at least once a year someone will need a doc I created and I'll get to her "Holy crap you write great docs!". That comment usually happens in a meeting with lots of people in it. Word gets around and my life is easier.