“Please don’t make me download a PDF!”

The icon on my desktop even looked clunky. That’s because I knew behind that 3 MB file was 75 pages of mostly XML. It was an example API documentation that I was supposed to emulate.

It was 2019 and I was looking at PDF documentation.

Indeed, when I recently asked for examples of bad documentation, I received multiple replies about the PDF anti-pattern. While thankfully less common, you’ll still find it in large enterprises and some government agencies.

The United States Postal Service (USPS) still has a PDF option:

Even its “HTM” versions feel like PDFs.

Direct mail company Lob took on a project to make this API more usable:

I share that story along with several others in Examples of Bad Documentation (And How to Do Better).

Let’s save developers from clunky PDF docs—and other mistakes that erode trust with technical audiences.

A great way to maximize your developer engagement is to have our team provide an objective review of your developer experience. You’ll get an assessment across 13 categories, a DX Index score, and a chance to debrief with our expert team.

​Book your DX review and give your team a solid foundation for developer engagement.