Principles Of Horrible API Documentation

I’ve worked a fair bit of my PM career leading the efforts in improving the API documentation experiences for developers. Nothing opens your eyes more to the pain of developers than actually building the tooling that makes API docs happen - you start encountering all kinds of quirky edge cases and corners of the API that you thought were simple enough but they are not. The more I saw that, the more I learned about just how big of a slice in the “Developer Experience” pie “API Documentation” is. Despite this, every time I try to fiddle with some API, SDK, or external component I inevitably stumble across a few where documentation is not only an afterthought but it’s often done so poorly that it might as well not be there. Which made me think - if one would set out to build the worst API documentation experience, what would it be?

I hereby present you the core tenets of absolutely terrible API documentation.

1. Make it manual. You only have a few APIs now. Maybe a few extra later. What’s the big deal with making developers hand-craft every single API documentation page? They can just put that as part of the release cycle. And by the time the API surface balloons to hundreds of classes with tens of parameters and hundreds of functions your developers are likely going to be accustomed to writing HTML files with their fancy text editors and IDEs so you’ll have it all published in no time.
2. If you can’t make it manual, auto-generate the barebones version - and never go beyond that. Your documentation is a reflection of your code and if your code is perfect, the docs are too. Yeah, there is no description for DataEgressJSONConverterFactoryFactory, but the name is self-explanatory, right? Besides, there’s only 25 functions in this class all starting with VOQW_ - what’s not to understand here?
3. Don’t bother with version control. You only need it for code anyway. Documentation is just a bunch of HTML files you can throw in a storage bucket behind a CDN. CI jobs? No, thank you. Just run a local script that uploads things to a blob container when the writing is done. You’re all in one team anyway and you’ll always coordinate uploads to make sure that changes don’t overwrite each other. As a bonus, you get to send HTML files around in email or your file share for review!
4. Leave out important information about required parameters or payloads. Developers need to learn through practice. Imagine how much better the learning process is if a developer has to literally disassemble your code to understand how it works. This is the true trial by fire, and in the end they will come out with a much better understanding of concepts that are completely irrelevant to the business problem they tried to solve in the first place.
5. Use as much technical jargon as possible. They invented search engines for a reason. You want to throw in as much PKIF, DOM, EOF, SSO, SOAP, ORM, SMACSS, SRP, OCP, and every other TLA you can possibly think of into the documentation to make it seem like it’s truly covering a serious and enterprise-ready API. You want to live up to the expectations of 10X developers.
6. Do not use examples. The only way to teach developers to get better at writing code is if they have to spend hours trying to figure out how to stitch your API together. Will this data query function return a raw JSON string or a serialized object? Only one way to find out! The data insertion function expects some XML though, so the developer better stumble upon IDataProcessorConverterFactory that needs to be implemented to properly transform the output from one function into the input for another. If you just gave an example, they’d run it and be on their way, and that’s not the way to build in-depth SDK knowledge.
7. If you use an example or two, make them out of date. The thrill of adventure really kicks in when you try to figure out if you have an older or a newer version of the library installed because the examples just don’t seem to match what’s in the API. Besides, you don’t have time to update examples - you have real work to do, like implementing more undocumented breaking changes (or, as they call them - Easter Eggs).
8. Make the documentation difficult to navigate. Only true developers understand that the documentation ideals were set in stone in the 90s. Seven <iframe> embedded on a page is how you want to make sure that you provide all the key information at once. True developers have 75" 4K displays that can accommodate this easily so you don’t need to worry much about the outliers. Search? As they say in New York, “fuhgeddaboudit!” Your users don’t need search, they need a tree view that shows all your classes, interfaces, functions, and properties at the same level. Give that mouse scroll wheel a purpose. Structure? The API is your structure.
9. Assume prior knowledge. You work on a complex product for 20 years. Your customers are the same, eh? Of course they are. They will know what the difference is between the audio API in kernel version 5.2.104 and 5.15.125-preview. You can just glance over all of that cruft and focus on the value - throwing some conclusions that you came to that others will then have to backtrack and spend days browsing some obscure mailing list for.
10. Don’t document error states or limits. A real developer writes code without errors. And if your customers encounter errors with your API, well, sounds like they better fix how they’re writing their code. Being rate limited? How about you teach developers to browse through their logs, aggregate the data, get median response times, and extrapolate what the limits are from that? See, you’re not only teaching them about your API but also important life skills, like being able to parse 45GB CSV files for something they will not need in 2 months.
11. Don’t document authentication flows. Let’s assume that you want to have your customers authenticate against your API. The only way to protect yourself from bad guys and people who would abuse what you build is by making it as complicated as possible. That means that if you don’t document how to authenticate against your API, bad guys can’t authenticate against your API. The dedicated developers that care about your product will figure it all out by firing up their local proxy and look at the REST calls flow from the outdated samples you provided a few years back. If they still work. If not, well, they better discover your OAuth 1.0 implementation with some twists that one intern added for extra obscurity three summers back.
12. Provide incomplete or inaccurate information about API responses. Yeah, so you needed to updated that JSON schema a few months back and you just never had time to document it. Who cares if half of the properties you made available before are not available? Your customers should’ve used your GraphQL endpoints anyway. Oh, it’s XML now? Well, I guess you better prioritize the work to move things to ProtoBufs because that’s where they hype is, which means you don’t need to document that old stuff anyway.
13. Use inconsistent conventions. One page calls this an entity, the other - an object. If your customers are lucky they might even stumble across a “metadata item.” Are they the same? Maybe. Or maybe not. You don’t care anyway, you’re not the one teaching them about all the minutiae of the awesome code that is being written as we speak.
14. Don’t provide any information about versioning. Everyone should be on the latest version anyway, so there’s really just one version you need to document. All those enterprises taking a dependency on your two-week-old library just need to get with the times and start thinking about right-clicking in the Solution Explorer and selecting “Update all NuGet packages.”
15. Don’t worry about accessibility. Pick whatever colors you feel give your documentation that cyberpunk vibe. Base in on whatever the latest trendy design framework a 5-person startup created for their marketing page. Don’t worry about ALT text on images because that’s just time you don’t have and besides, AI is getting better and it’ll start narrating images soon anyway.
16. Have dead links and pointers to outdated resources. Your customers know there is a thing called archive.org where they can look at old versions of pages no longer available, right? Well, they do now. You don’t have time to update all those links or write validation automation. It’s exciting to get an occasional 404 - it’s like a treasure hunt you’re forcing your users to go on to find the treasure in the shape of a snippet that hasn’t been updated in a decade.
17. Make it difficult to report issues or receive support. Your documentation is perfect as is. You don’t need no ideas, suggestions, comments, or feedback. And if your users have feedback, that just means they are using the API wrong, which means that need to start reading your documentation more. See? Easy.