When developers create a product, whether it's an SDK or something else, they obviously intend for it to be used by others who need it to suit their purposes. However, they tend to focus more on getting the code to work properly without taking the documentation into consideration.
I spent a month on GitHub perusing documentation that I could contribute towards, and something I noticed is how little effort many developers put into it. For personal projects, this is understandable since most of those projects are demonstration pieces, and most developers likely aren't going to be interested anyway. However, I've come across libraries that seem to dump all of their information into the README file and then forget about it.
I'll use BCryptJS as an example since it's a library most everyone in web development is familiar with. There are only a handful of methods for it — and only two of which are ever going to be used at most — so its length isn't as much of a problem as it otherwise could be.
The real problem with this documentation is that it almost feels like it was written for the developers who maintain it rather than for developers in general.
Here's a sentence from their "Security Considerations" section:
"While bcrypt.js is compatible to the C++ bcrypt binding, it is written in pure JavaScript and thus slower (about 30%), effectively reducing the number of iterations that can be processed in an equal time span."
Most developers will read that and wonder why it's relevant to them. Why do they care about its compatibility, or how often it iterates compared to such and such? It's certainly interesting, but it's also not useful to someone who just wants to protect user data.
One other flaw that I noticed in their documentation is that they don't really mention how salting user passwords can affect the speed of requests. They reference "computation power" in the aforementioned security section, but it's more in reference to BCrypt as an adaptive function rather than any particular method. I had to learn the hard way that a salt greater than 10 — their default value — tends to increase the time it takes to process a request. In hindsight, it's fairly obvious, but part of writing documentation is understanding that what's obvious to you isn't obvious to others.
A more general problem that I've noticed with developers is that many of them will open an issue on GitHub for help with documentation, only for them to assign the issue to themselves and rarely resolve it. I don't mean the cases where they assign themselves because the issue's been open for two weeks and no one's volunteered. I mean the cases where the issue's only been open for less than a day, it's clearly low priority to the developer, yet they choose to assign themselves anyway. Then, because of its low priority status, the issue goes unresolved for weeks. This can have the unintended consequence of creating documentation that isn't as informative as it should be, whether it's because of missing sections, lack of organization, or overuse of jargon.
I suspect that some of these developers have a "look but don't touch" mindset when it comes to their work. It's an understandable one to have, but I think development is almost inherently a collaborative effort. Developers have their own approach to how they code, but that can also make them unable to see the flaws in their work. The way they document their products is no different. They may understand every intimate detail, but that doesn't mean they can translate it for developers who know nothing about it.
Documentation isn't just about telling users what the product is, or how to use it. It's also about getting them to understand it. When a user discovers a product, whether it's software, a kitchen appliance, or anything else, they're naturally going to want to figure out how it can suit their needs. If that user isn't given a means to understand why that product is important, then they likely won't bother with it. Documentation should be the means of achieving that, but it can't do so if the developer isn't considering the needs of the user when making their product. The key to good documentation is to treat it not as an accessory to the product, but as part of the product itself.
Top comments (0)