Bad documentation is bad for developers
• 11 mins
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
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 availablebut hard to find because it’s hosted on another site or buried inlayers of menus.
- Similarly, documentation can exist and be easy to find but presentedin 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.