Bad documentation is not an accident. The missing API parameters, the tutorials that stop halfway, the reference pages that describe what a function does without explaining when to use it — these are not the result of engineers who couldn’t find time to write clearly. They are, in many cases, a deliberate product decision with measurable business returns.
That is a difficult claim to accept, because incompetence is the more comfortable explanation. But follow the incentives and the pattern becomes hard to ignore.
Confusion Creates Dependency
When documentation is genuinely good, users become self-sufficient. They solve their own problems, build their own integrations, and rarely need to call anyone. When documentation is selectively bad, the same users turn to paid support tiers, certified partner networks, and professional services arms.
Salesforce is the clearest example of this in practice. The company’s documentation is voluminous, technically detailed, and structured in a way that rewards specialists while frustrating generalists. Learning Salesforce properly requires either years of experience or hiring someone who has it. That friction is not incidental to Salesforce’s business model — it is the business model. The Salesforce partner ecosystem, which funnels billions of dollars annually through consultants and implementation firms, exists largely because the platform is difficult to use without help.
The same pattern holds for enterprise software broadly. Oracle, SAP, and similar companies have built entire professional services divisions on the premise that customers will need ongoing guidance. Clear documentation would cannibalize that revenue.
Incomplete Docs Protect Competitive Position
There is a second motive that gets less attention: incomplete documentation keeps competitors guessing. If a platform’s internal architecture, undocumented parameters, and edge-case behaviors are never written down, third parties cannot easily replicate or build against the full surface area of the product.
This connects to something broader about how tech companies think about intellectual property. Software copyright protection can last nearly a century, and undocumented behavior sits in a legally ambiguous space that companies are often happy to leave murky. If a competitor reverse-engineers an undocumented API and builds on it, the platform owner has options. If that same behavior is in the public documentation, those options narrow.
Apple’s developer documentation has long had gaps around private frameworks and internal APIs that third-party developers are technically prohibited from using. The prohibition is enforced inconsistently, but the documentation gap makes it harder for outsiders to even identify what they’re not supposed to touch.
Confusion Filters for High-Value Users
Not every company benefits from accessible documentation. Developer tools companies in particular often want their user base to skew toward technically sophisticated users, because those users build the integrations, write the tutorials, and generate the word-of-mouth that drives organic growth. Making the initial documentation difficult filters out casual experimenters and leaves the committed ones.
Twilio, Stripe, and AWS all launched with documentation that was technically dense but rewarded careful reading. The pattern wasn’t accidental — each company was explicitly targeting developers who would work through friction, not despite it. The complexity signaled seriousness. Stripe’s API documentation is now widely cited as excellent, but it got there gradually, after the user base was already committed.
This filtering logic also explains why companies improve documentation when they move upmarket toward enterprise buyers (who have dedicated technical staff) rather than when they move toward consumers (who need simplicity). The documentation quality tracks the customer profile, not the company’s maturity.
The Ecosystem Play
Confusing documentation also creates space for a third-party knowledge economy that ultimately benefits the platform owner. Stack Overflow answers, YouTube tutorials, paid courses, and certification programs all exist because official documentation leaves gaps. The platform company pays nothing for this content, but it deepens user investment in the ecosystem.
Microsoft’s Azure documentation has enough gaps and outdated pages that a cottage industry of Azure-focused trainers and bloggers has grown around filling them. Those trainers then promote Azure to their audiences, run certification prep courses, and generally do marketing work that Microsoft doesn’t pay for. The documentation gap is effectively being subsidized by third-party content creators who need the gap to exist.
The Counterargument
The obvious pushback is that most bad documentation is simply the result of engineers who don’t like writing, product teams that don’t budget for technical writers, and companies that deprioritize docs because documentation doesn’t show up in quarterly metrics. This is true, and it accounts for a large share of the problem.
But “neglect explains most bad documentation” is different from “neglect explains all bad documentation.” The cases where documentation gaps align suspiciously well with revenue streams, competitive moats, and partner ecosystems deserve a more skeptical reading. Neglect and strategy are not mutually exclusive, and companies that benefit from confusion have little incentive to fix it, regardless of how the confusion originated.
How to Navigate It
Knowing the motive changes how you approach the problem. If documentation gaps exist to create professional services revenue, the fastest path forward is often finding a consultant or certified partner who has internalized the undocumented behavior through paid client work. That’s an expensive solution, but it’s what the incentive structure is pointing you toward.
For developer tools specifically, the third-party knowledge economy is usually more current and more practical than official docs. GitHub repositories, community forums, and tutorial blogs fill the gaps that official documentation leaves open, often faster and more accurately.
For anything mission-critical, build a relationship with the vendor’s support team before you need it. The companies that deliberately use documentation complexity as a sales funnel have made the support relationship the product. Treating it as such, rather than as a last resort, puts you closer to where the real knowledge lives.
The companies that write clear, comprehensive, genuinely useful documentation do exist. They are worth identifying and rewarding with loyalty, because they are choosing a harder path than their competitors.
