Bad documentation is bad for developers
Documentation tends to be bad because companies and projects don’t fully realize the costs of bad documentation.
The Python documentation is bad.
Why is Docker’s documentation so bad?
Documentation Sucks:(
The above are just a small selection of HackerNews submissions, each of which demonstrates a well-known problem: Documentation is frequently bad.
Developers often commiserate about frustratingly bad documentation but despite that consensus, bad documentation remains (and more is produced every day). The argument I’m going to make here is that documentation tends to be bad because companies and projects don’t fully realize the costs of bad documentation.
Without a sense of cost from having bad documentation or a sense of benefit from having good documentation, it’s inevitable that most documentation will sink to the lowest common denominator.
To see how, I’m going to walk through three ways bad documentation hurts companies and projects:
- Bad documentation makes products harder to understand and use.
- Bad documentation makes products harder to market
- Bad documentation makes development frustrating and time-consuming.
And to illustrate, I’ve found some examples of bad documentation and people making these complaints – and their related costs – known.
3 reasons bad documentation will hurt you #
Documentation is frequently an afterthought, a step tacked onto the end of development (if it’s tacked on at all). Startups tend to think they have bigger priorities and enterprises tend to have so much software to document that the entire idea becomes overwhelming and hard to manage.
Similarly, developers sometimes start the development process without proper design and requirements documentation. This documentation is rarely visible outside the company – it’s like trying to build a house without a blueprint – but it creates the same kind of problem. Development without documentation damages the company.
As an industry, we struggle to define clear expectations about what truly good documentation entails. That said, while the ceiling on good documentation is high, the floor is quite low and if we bust the myth that developers can’t write, minimally effective documentation is more achievable than you might think
1. Bad documentation makes it hard for customers to use your product #
Developers are notorious for wanting to get their hands dirty and learning software through the process of using it. But eventually, reading the documentation becomes necessary.
Sometimes this is the fault of the product. For new projects and companies, the UX and onboarding might not yet be good enough for users to learn while using.
Other times, the primary user is experienced and the software is well-designed but other, less experienced users struggle. If you’re building a security product, for example, sysadmins who aren’t security experts might be in charge of implementing the product and they might need good, clear documentation.
In both cases, documentation becomes something of a product feature and in that light, it’s important to make the feature usable enough that the product itself can become approachable.
2. Bad documentation makes your product harder to market #
Developer marketing is notoriously difficult. The level of effort required makes it all the more frustrating when bad documentation undoes all that hard work.
Even if good marketing and a great product cultivates curiosity and interest, bad documentation can make conversions (such as signing up for a demo or trial account) less likely. For many developers, poorly written or disorganized documentation instantly signals a lack of technical credibility. Even if they respect the product, bad documentation can either sow doubts or convince them to wait for the product, company, and documentation to get better.
If you look, you can find examples. On a public post in a forum for Syncfusion (a company that provides component libraries), a potential customer wrote the post Very bad documentation and example on ScheduleQuickInfoTemplates.
In the post, the potential customer explains they are “still in [the] evaluating phase” but that this bad documentation “is a show stopper for us.” After illustrating with a few examples, the customer writes that “This is really annoying and not very developer friendly” and concludes the post with an ultimatum: “Now I'm awaiting your answer [and] then we decide if it is worth buying [these] components.”
Be careful not to assume this kind of complaint is rare. Not everyone will post a complaint publicly. Given how often developers complain about documentation in general, though, I suspect experiences like this are pretty common.
3. Bad documentation makes developer onboarding harder #
Developer onboarding is what turns a skilled but newly hired developer into an effective team member. Often, this process is undervalued and new developers can struggle to learn and veteran developers can tire of answering their questions.
Developer onboarding also involves experienced developers switching teams and learning new parts of the codebase or developers trying to collaborate across teams and features.
For both forms of developer onboarding, good documentation is essential but often deprioritized.
Bad documentation obscures rather than clarifies. Developers can read it and struggle to understand how the product really works and what the feature they’re assigned to depends on. Confusion accumulates over time and shows up in weird ways with developers getting frustrated, iteration taking longer than expected, and collaboration becoming something developers avoid rather than pursue.
There are downstream effects too – costs that pass from developers onto others. Without good documentation, QA analysts, product testers, technical writers, customer success agents, and security engineers can all struggle to do their jobs.
If a huge, zero day vulnerability like Log4j drops, for example, a security engineer might need to pore through code they’re unfamiliar with to find instances of the vulnerability and good documentation makes that much easier.
6 examples of bad documentation #
Bad documentation abounds and you can find it anywhere from tiny open source projects to huge enterprises. I’m sharing these not to embarrass anyone but to show some of the myriad ways documentation can become ineffective.
1. DITA has confusing language #
When a Reddit user asked for examples of bad documentation, the documentation for DITA (an open standard for document organization) was first to mind for another user. In this post, the user explains that, to an outsider, the DITA documentation reads as though it was “written by someone who eats, sleeps, and dreams DITA, to the point where they can barely communicate with civilians anymore.”
The user even picks out a particular passage from the DITA 1.2 specification:
…if the referenced element is the same type as the referencing element, and the list of domains declared on the domains attribute in the referenced topic or map instance is the same as or a subset of the list of domains declared in the referencing document, the element set allowed in the referenced element is guaranteed to be the same as, or a subset of, the element set allowed in the referencing element.
Take a second to read it. If you’re confused, you’re in good company: The user says this passage is “seared into [their] memory.”.
As the user suggests, developers and maintainers might need to step outside of their expertise and either consult technical writers or end-users to see if the documentation they’ve written makes sense.
2. NodeGit offers too little context #
In the same parent Reddit post, another user has a different example that comes immediately to mind: NodeGit.
This user is blunt, writing that “The nodegit docs are the worst that I've had to use.” After some brief “starter info” at nodegit.org, they write, “they throw you into this mess” and link the NodeGit API docs.
As you can see in the screenshot above, the documentation is extensive but lacks context and explanation. Another user, apparently horrified after clicking the link, writes that the documentation looks like “someone just barfed out a YAML/JSON file into an HTML generator and called it a day.”
The original user also writes that “It's not THAT hard to write a basic bloody sentence describing what each call does with a copypasted example of what to expect if it works.”
This feedback gets back to why I’m sharing these examples: Bad documentation examples like these show why documentation needs to at least be minimally viable.
3. USPS provides PDFs #
Lest we focus too much on open source projects, let’s turn to a huge organization: The United States Postal Service (USPS).
Here, I don’t even want to talk about the quality of the documentation itself because USPS makes a fundamental mistake. As you can see below, users have to either download a PDF or click through to an HTML version.
Links to an HTML (or “HTM”) version provide some hope but clicking on them reveals documentation that appears, at least aesthetically, to be decades old.
A basic Markdown document hosted on GitHub is often more useful than a better written or presented PDF. With Markdown, developers can at least copy-paste and share links to particular sections.
4. Microsoft doesn’t explain terminology or offer examples #
We can find bad documentation from major enterprises too.
In a post on Microsoft’s developer community, a user complains of “bad documentation of C#, in fact horrible documentation.” The user goes on to write that “the documentation of C# is the worst explanation I’ve ever seen!!”
The documentation in question has since been improved. The improvements were partially thanks to this user, who went into much greater detail in a now closed issue.
Across the nearly 50 bulleted complaints, two themes emerge: The documentation didn’t clarify terminology and the documentation didn’t provide examples.
The original post also provides a helpful frame for our purposes because the user classified the severity of the issue like this: “[severity:It’s more difficult to complete my work].” Here, we see clear evidence that the first cost with bad documentation we described above (that bad documentation will make your product harder to use) bears out.
5. Hugo and UglifyJS introduce breaking changes #
If you ask for examples of bad documentation, as technical writer Heydon Pickering did on Twitter, one common complaint you’ll find is products that introduce releases with breaking changes but without documentation that explains those changes.
One person cites Hugo, an open source static site generator.
In a post on Hugo’s support forums, a user suggests that “there should be a warning in the console when building sites with 0.60.x about this (if one or more instances of unsafe HTML are detected and removed by the renderer, emit one warning)” because, the user suspects, “a ton of users will hit this issue and have trouble resolving it.”
The creator of Huge, Bjørn Erik Pedersen, responds: “No.”
Another Tweet cites breaking changes from UglifyJS, a popular JavaScript parser. In one issue, a user complained that a new version only included a list of commits and didn’t include a changelog or blog post. The developer didn’t address the substance of the complaint and instead thanked the user for their “insightful comments” and closed the issue.
Breaking releases are sometimes necessary but without documenting those changes, users will struggle to migrate or adapt and even committed users can become frustrated.
6. 404: Documentation not found #
Clearly, the quality of documentation can vary widely and bad documentation can vary from bad to worse. But even then, the worst documentation is the kind that is unavailable or inaccessible.
There’s a few ways this problem can show up:
- There could be no documentation at all.
- There could be documentation but it might only be available upon request.
- There might be documentation but it could be behind an account login.
- Sometimes, the documentation exists and is technically available but hard to find because it’s hosted on another site or buried in layers of menus.
- Similarly, documentation can exist and be easy to find but presented in a format that’s hard to consume. Code screenshots, videos, and overly busy diagrams, for example, makes software look more confusing than it even is.
No matter how good the documentation is, it’s ineffective if developers can’t find it.
Prioritize documentation the way it deserves #
The takeaway I want to leave you with is not to judge any individual developer, project, or company but to instead see these examples as part of a larger pattern: As an industry, we do not effectively reinforce the importance of documentation.
There are numerous ways to improve documentation and numerous ways to integrate documentation into your development process. You could add documentation to your software life cycle and make it an essential step for developers working on new changes, for example, or you could hire a technical writer who can make documentation their primary priority.
Solutions and strategies are out there and there’s good documentation that proves they work. But documentation, as a whole, remains generally mediocre because we’re not recognizing the costs. If we did, I think, good documentation would become a priority.