Good technical documentation is essential for effective communication and understanding of your product. It helps users understand how to use and troubleshoot the technology, and it can also serve as a valuable resource for developers to understand the design and implementation of the system. Clear and comprehensive technical documentation can greatly improve a developer’s experience with your product.
On the other hand, poor technical documentation can lead to confusion and frustration for developers, as well as wasted time and resources. Examples of poor documentation include non-existent or difficult-to-find pages, broken documentation with incorrect or broken links, and inaccurate docs that don’t reflect the current state of the product. Poor documentation makes it difficult for developers to understand the product and slows down the development process.
In this post, we will examine the various types of poor documentation and provide examples, solutions, and best practices for creating comprehensive and effective technical documentation for developers.
1. Can’t Find It or It’s Not There
Perhaps the worst documentation is the one that doesn’t even exist. Developers look for your docs to see what’s possible. There’s no way to tell what you can build if documentation isn’t made available. That said, this bad docs mistake still comes in a couple of flavors.
The first is purposely hidden documentation. Despite the well-known dev desire for self-sufficiency, many organizations still purposely withhold documentation. The business reasoning here is that you can better understand what someone is looking to solve. Unfortunately, the vast majority of developers will never reach out to request your documentation.
Other companies hide documentation behind a login, often for similar reasoning. A free account usually requires an email address, which means you’ll have a way to contact the potential customer in the future.
Again, many devs will want to see the docs to decide whether it’s worth creating an account.
The last two non-existent docs issues appear exactly the same to devs:
-
- Documentation is not prominently linked
-
- Documentation has not been written yet
If your audience can’t find it, it might as well not have been written. The solutions to these problems, of course, are very different. Your team will either need to create the docs or make them discoverable on your website.
In our recent review of top dev company homepages, only about half mention developers or documentation in global navigation. Of the remaining companies, almost all of them provide a documentation link one more click away, usually under a “resources” menu.
2. Broken, Inaccurate, and Outdated
Some may argue that wrong documentation is worse than no documentation. Indeed, this is consistently listed as a top frustration of developers. Of course, there are a number of ways that documentation can be wrong.
It might be an edge case that’s not covered, like returning a null field when something is expected. Or the classic API mistake of an error message mixed with a 200 status code that suggests all is OK.
Problems of incomplete documentation are hard to find and infuriating when developers bump into them.
You can have other issues that are easier to discover and still annoying for someone browsing your docs. We frequently find links within documentation that go nowhere—404 in web parlance. Now imagine it’s the exact page you need to complete your project.
Once, I received a report from a developer that our product had “read more” links as plain text, without actually linking. I scoured the docs, but couldn’t find it. Eventually, deep within the dashboard, was helper text that had somehow been stripped of its links. Even worse, there were several of them and we couldn’t figure out how long it had been that way.
Whether it’s wrong because something has changed or it was never right in the first place, what’s important is what happens next. Yes, there are processes you can put in place to catch some of this automatically, but make sure there’s a clear line of communication with devs. Make it clear where to get support, provide a feedback tool for every docs page, and—here comes the hard part—read and react to the bug reports.
Hundreds of marketers like you subscribe to EveryDeveloper Weekly to learn the latest developer engagement lessons, covering content strategy, developer experience, and more.
3. Click Here to Download the Docs
When I asked around for bad documentation examples, there was one immediate response. In fact, you can use this acronym with most developers and see a visceral reaction to this particular document format. For years, I counted on it as a punchline in talk, just by showing this image.
Yes, PDFs are the classic bad docs experience embedded in developer brains. The document itself makes it difficult to browse, copy-paste, and share deep links with other developers. But the aversion may go to the types of products that are documented in this way. Usually, it’s a sign of other problems.
For example, take a look at the US Postal Service docs (USPS). Granted, there’s a non-PDF version, which they somehow make feel like a PDF (and that “HTM” extension alone inspires a grimace).
In fact, while at Lob, Sid Maestre published a modern version of the USPS docs. Many devs may still find problems with the API (such as XML responses), but uspsweb.tools is a huge improvement over the legacy experience.
Of course, PDFs are just one file format of several you might see: Word docs, Excel, Powerpoint, and many others have been reported. Even an OpenAPI document, a format we love for its contributions to DX, is not sufficient documentation.
Lastly, the other problem with downloads is they’re often paired with a sales form. If devs hate PDFs, I’m not sure there’s a strong enough word to describe how they feel about sales forms.
4. The One-Trick Pony
You can do none of the previous documentation mistakes and still not provide documentation that helps devs. Most commonly, we see this with reference-only documentation. It tells you all the facts you need to use a product, but nothing to help you connect the dots in the right order. Despite what devs may even say themselves, “just show me the docs” doesn’t work.
The classic sign that there’s only one type of documentation is when your docs are nearly indistinguishable from the default Swagger Petstore.
In addition to a reference, which only covers the functional details, you want to include other types of documentation:
-
- Contextual “why this matters” documentation
-
- Tutorials to take you step-by-step through a project
-
- Sample apps and code snippets to solve common problems
You might even consider switching up the format. Experiment with video and other ways of communicating about your product, such as these innovative tutorial formats.
5. No Opinion, No Narrative
Somewhat related to the one-trick pony, this final bad documentation example is worthy of its own section. Including multiple types of content does not necessarily mean the story will resonate with the audience. Even documentation should include some voice of the company.
Your docs need to explain more than how someone builds with your product. They must explain why developers would want to integrate it.
Many Google APIs use a structure that helps them avoid being a one-trick pony without any narrative. Guides, in particular, are where the company shares its important use cases—and, yes, how to implement them.
It’s in these guides that you might also be able to inject some of your company or product opinion. That may run counter to how you think of documentation. The most opinionated content will likely be published on your blog, but consider that your product exists because it solves a need in an opinionated way. Don’t hide it—share it and you’ll help developers have better, faster success with your product.
Learn From Great Documentation
It’s one thing to avoid these documentation mistakes, but it may be better to look at the ones that get it right.
We’ve collected nine of the best API documentation examples, including Plaid, Twilio, and Stripe. Rather than copy everything one company does, why not take the best from each? The post covers the full spectrum of documentation types and best practices.
If you need guidance from the EveryDeveloper team, the best way is to reach out for our objective opinion. We can perform a DX Review, which includes your documentation and other areas that impact the developer experience.
Hundreds of marketers like you subscribe to EveryDeveloper Weekly to learn the latest developer engagement lessons, covering content strategy, developer experience, and more.