Nobody Makes Bad Documentation on Purpose

The most important element to developer success, with APIs, open source, or other tools, is documentation. Yet, any developer will tell you that most of it isn’t very good. Bad documentation happens on accident, for a lot of reasons…

Adam DuVander
Jul 14, 2016 · 1 min read

Busy working on the product

Don’t know enough about the product

Know too much about the product

Haven’t found the time to focus on it

Not sure what needs to do in the docs

Haven’t encountered your undocumented problem before

Too busy with support requests

Too busy with sales

Haven’t hired that role yet

Docs are “good enough”

Developers aren’t their core customer

Waiting to finish a redesign

Want to completely re-imagine the documentation experience

Too many products to document

Nobody thinks it’s their job

Everybody thinks it’s their job

Well-designed products shouldn’t require documentation

They’re working on it

Trying to get a good framework in place

Don’t understand what the audience wants to know

They’re a marketer not an engineer

They’re an engineer not a tech writer

They’re a tech writer not a marketer

There’s too much going on

Everything else gets a higher priority

Not sure how to make them better

And many more… which ones did I miss? Let me know in a response.

Improve your documentation and developer experience by learning from successful APIs. Subscribe at

Every Developer

We all help make technology

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store