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.

Author
Knut Sveidqvist
Creator of MermaidJS and founder of Mermaid Chart