What’s missing from your docs?

Functionality is not enough.

The bar for most docs should be higher than just providing the information to make something functional.

When I bought a Vespa-like motorized scooter off the internet, some guys delivered a heavy box to the curb. They could not take it farther.

I opened it on my sidewalk:

Inside were handlebars, fenders, the rest of the scooter, and a pamphlet about its electrical system.

Nothing about how to assemble it, nor a heads up that the battery was unplugged for safety. And certainly nothing about care or maintenance.

Just electrical schematics. The information to make it technically functional.

I see similar approaches with documentation all the time. Companies will provide an OpenAPI description, for example… and nothing else. Developers have the tools, companies often reason, to import a machine-readable list of inputs.

And I suppose some electric scooter owners know what to do with wiring schematics, too.

​OpenAPI can impact DX, but it’s most useful when converted into other documentation. For example, you can create an interactive reference or SDKs for popular languages.

Even then, it’s a format about functionality. Great documentation also includes context: how your product is used and why it matters.

Both marketing and documentation teams should spend the bulk of their focus on the context.

If you’re curious how you can do that, start with these three ideas to improve your DX without changing your product.