Every Developer Documentation Audit check

A missing or skeletal README is the single most common reason developers abandon a project within the first five minutes. Without a clear statement of what the project does and who it is for, every potential contributor, integrator, or evaluator must read source code to answer the most basic questions. iso-25010:2011 analysability directly penalizes this: a project that cannot be understood without reading its implementation is expensive to maintain and impossible to evaluate. Vibe-coded projects routinely ship with boilerplate placeholders — 'TODO: Add description' or 'This project was bootstrapped with create-next-app' — that communicate nothing.

Why this severity: Critical because a project with no meaningful README cannot be evaluated, adopted, or safely integrated by any external developer, making the entire codebase effectively undiscoverable regardless of its technical quality.

Incomplete or missing installation instructions force every new developer to reverse-engineer the setup from source — inspecting package.json, searching for environment variables, and guessing at post-install steps. This breaks the adoption funnel at its first step. iso-25010:2011 analysability measures exactly this: the effort required to understand a system before using it. Vibe-coded projects frequently include generic boilerplate like a bare 'npm install' with no package name, no repository URL, and no mention of required setup steps that follow.

Why this severity: Critical because without precise installation instructions, no external developer can run the project at all — every missing step multiplies abandonment probability, making adoption effectively impossible for anyone without insider context.

A missing or bloated quick start is the single strongest predictor of project abandonment. Developers evaluating a library spend 60 to 90 seconds deciding whether to integrate; if they cannot reach working output in that window, they bounce to a competitor. This translates directly to adoption loss, lower GitHub stars, lower npm downloads, and fewer inbound contributions. Teams integrating internally waste hours piecing together setup from scattered docs, inflating onboarding cost per engineer.

Why this severity: Critical because first-impression friction directly kills adoption and there is no workaround for the evaluator.

Undocumented prerequisites turn a five-minute setup into an hour of debugging. When a project silently requires Node.js 18+ for native fetch, a running Postgres instance, or an active Stripe account, developers on Node 16 or without the external service hit cryptic runtime errors with no path to resolution. iso-25010:2011 analysability treats prerequisite documentation as a core input to understanding a system. The failure mode is invisible: the code looks correct, the install succeeds, and then execution fails for reasons that have nothing to do with the code itself.

Why this severity: High because missing prerequisites cause silent environment failures that block setup entirely, and the resulting errors are rarely self-diagnosing — developers waste significant time before discovering the real dependency.

Undocumented environment variables force every new developer to grep the codebase for `process.env.*` references and guess at formats, values, and provisioning steps. Missing variables cause silent failures at runtime (databases not connecting, API calls 401ing, features toggling off) that waste hours of debugging. For production deploys, an incomplete `.env.example` is a common cause of broken releases when a required variable is forgotten in the deploy pipeline's secrets store.

Why this severity: High because undocumented env vars block every new contributor and cause silent production failures.

Without a contributing guide, the implicit message to every potential contributor is: figure it out yourself. Developers who can't run the test suite, don't know the branch naming convention, or don't understand the PR review process submit lower-quality contributions or don't contribute at all. iso-25010:2011 analysability covers this: a project is more maintainable when its development workflow is documented rather than implicit. Generic templates ('fork the repo and submit a PR') fail entirely — they don't mention how to run the actual test suite or set up the project-specific dev environment.

Why this severity: Low because the failure mode affects contributor throughput rather than end-user functionality, but repeated over time it compounds into a maintainability tax that stalls pull requests and discourages external participation.

An undocumented public API surface forces every consumer to read the source to understand what a function accepts, what it returns, and when it throws. At scale this is a critical iso-25010:2011 analysability failure: every hour a developer spends reading implementation code instead of documentation is a direct tax on adoption and integration speed. The 80% coverage threshold exists because partial documentation is worse than none — it creates false confidence, leaving the undocumented 20% as silent landmines. TypeScript types alone do not satisfy this: a type signature names parameters but doesn't explain their semantics, valid ranges, or side effects.

Why this severity: Critical because an undocumented API surface makes the project unusable to any developer without source access, and partial documentation creates false confidence that leads to incorrect integrations at runtime.

Prose API documentation without working code examples asks developers to mentally simulate execution from a description — an error-prone process that slows integration and increases incorrect usage. The iso-25010:2011 analysability principle is clear: documentation that enables correct use without reading source is the standard. Pseudocode and incomplete snippets (missing imports, unrealistic parameter values, no expected output) fail this standard. Outdated examples that use deprecated APIs are actively harmful: they send developers down dead-end integration paths using methods that no longer exist.

Why this severity: High because missing or broken code examples force developers to experiment against a live API to understand basic usage, dramatically increasing integration time and the likelihood of incorrect implementations.

REST and GraphQL API consumers can't integrate correctly without knowing exactly what to send and what to expect back. Documentation that describes an endpoint without showing an example request and response forces developers to guess at header formats, body structure, and response shapes — every guess is a potential bug. OpenAPI specs with 'string' placeholders for every field value are no better than no docs at all: they show structure but not semantics, valid values, or what realistic data looks like. iso-25010:2011 analysability requires that a system be understandable without probing it experimentally.

Why this severity: High because API consumers who cannot see example request and response payloads must probe the API experimentally, introducing integration bugs and making the first-use experience unreliable.

When an API returns a 401, 422, or 429 and the docs say nothing about error responses, developers have no way to write correct error handling — they cargo-cult whatever they saw in a Stack Overflow answer. Libraries that throw custom error classes but never document them force consumers to catch generic Error and inspect message strings, a fragile pattern that breaks across versions. Every undocumented error is a latent incident: the integrator doesn't know the error is possible, doesn't handle it, and a user sees an unhandled exception. iso-25010:2011 analysability covers this: a system where all failure modes are documented is fundamentally more maintainable than one where they are discovered at runtime.

Why this severity: High because undocumented error codes mean consumer applications cannot implement correct error handling, turning every production failure into a novel debugging session rather than a handled case.

Authentication is the first real barrier every API consumer hits, and undocumented auth setup stops adoption cold. A `.env.example` that lists `API_KEY=` without explaining what that key is, where to get it, or how to include it in requests leaves developers at a dead end. For OAuth or JWT flows, missing documentation means developers either skip auth entirely in development or implement it incorrectly, creating security exposure. iso-25010:2011 analysability and user-experience quality both depend on auth documentation that includes the full flow: obtain credential, include in request, handle failure.

Why this severity: High because undocumented authentication makes the API unusable in practice — developers cannot make a single authenticated request without guessing the credential format, and incorrect implementations produce silent security gaps.

An API that returns 429 without documenting its limits forces consumers to discover the ceiling experimentally — in production, under real traffic, during a critical path. Rate limit headers (X-RateLimit-Remaining, Retry-After) are useless if consumers don't know to read them. Undocumented quotas also block capacity planning: a company considering integration cannot evaluate whether a free tier meets their use case without knowing the specific numbers. iso-25010:2011 analysability requires that all operational constraints on a system be documented, not discovered.

Why this severity: Medium because the failure creates operational surprises rather than blocking initial adoption, but undocumented rate limits lead directly to production incidents when integrators hit limits they didn't know existed.

Non-runnable code examples are an AI-slop hallmark: imports that point at fictitious packages, function names that never existed, parameter signatures that drifted two versions ago. When a developer pastes your example and it throws `Module not found` or `TypeError: x is not a function`, they lose trust in every other claim in your docs. This is a reference-integrity defect that wastes evaluator time and signals an unmaintained project, tanking adoption and inviting support tickets for problems your docs created.

Why this severity: High because broken examples destroy trust on first paste and block integration outright.

Placeholder text (`TODO`, `TBD`, `FIXME`, `Coming soon`, unmodified `create-next-app` boilerplate) tells every evaluator that the project is unfinished and the maintainers are not shipping. It is worse than an absent section because it actively signals neglect. For commercial libraries this kills sales; for open-source projects it suppresses stars, contributions, and external integrations. Boilerplate READMEs also leak through search results and SEO-penalize the project against competitors who wrote real content.

Why this severity: High because placeholders actively signal project abandonment and erode evaluator trust immediately.

Inconsistent terminology in documentation signals to readers that the codebase was written in separate sessions without coordination — because it usually was. When 'API key' in the authentication section becomes 'token' in the code examples and 'credential' in the error reference, readers must constantly re-orient to confirm these are the same thing. For vibe-coded projects built across multiple AI sessions, terminology drift is nearly universal: each session invents its own names for the same concepts. iso-25010:2011 analysability is directly degraded by terminology inconsistency — the documentation costs more cognitive effort per reading.

Why this severity: Medium because terminology inconsistency doesn't prevent use outright, but it compels every reader to do disambiguation work on every reading, multiplying comprehension cost across the entire user base.

REST APIs and multi-language SDKs with examples in only one language silently exclude entire developer audiences. A Python backend engineer evaluating your API should not have to mentally port JavaScript examples; a mobile developer working in Swift should not need to read curl to figure out a request shape. The cost is measurable in rejected integrations, drive-by support tickets ("how do I do this in Go?"), and underperforming SDKs whose docs languish behind the flagship language.

Why this severity: Low because missing language coverage is a discoverability friction, not a broken integration.

When the same question surfaces repeatedly in GitHub issues, Discord, or Stack Overflow and never lands in your docs, every maintainer hour spent re-answering it is a recurring tax. Users who hit a setup error without a troubleshooting entry either open a duplicate issue (inflating support load) or abandon the project silently. Documented troubleshooting converts recurring pain points into self-service, reducing issue volume and improving time-to-first-success for new users.

Why this severity: Low because absent troubleshooting scales support cost but does not block a careful user.

Documentation that describes a v1 API in a project now on v3 is worse than no documentation: it actively sends developers down paths that no longer exist. A 'npm install package@1.2.0' command in the README when the current version is 3.0.0 installs broken software. Code examples showing deprecated methods produce runtime errors with no obvious cause. iso-25010:2011 analysability requires that documentation reflect the actual current system, not a historical one. For vibe-coded projects that iterate rapidly, docs are frequently written once for an early version and never updated as the API evolves.

Why this severity: High because stale documentation sends developers down dead-end integration paths, producing runtime errors from deprecated or removed APIs that cannot be resolved without reading source code.

Broken internal links are a reference-integrity defect: a README that points at `docs/api.md` after the file moved to `docs/reference/api.md` tells users the documentation is out of date and unreliable. Dead anchor links, missing image badges, and links to source files that were renamed in a refactor all accumulate after restructures. Each broken link is a dead end in the user's journey, and at scale they collectively destroy the navigability of the docs.

Why this severity: Medium because broken links cause dead ends but most users find alternate paths.

An 800-line README with no table of contents or a `docs/` directory of 12 unindexed markdown files forces users to scroll, grep, or browse the file tree to find anything. Users who cannot navigate the documentation in under 30 seconds either give up or ask the maintainer directly — both outcomes inflate support cost and suppress adoption. Search engines also rank documentation with clear navigation and anchor links higher, compounding the discoverability loss.

Why this severity: Medium because poor navigation slows every user but does not block any single task.

A breaking change without a migration guide forces every existing user to diff the changelog, read source code, and guess at the new equivalent. A CHANGELOG entry that says 'BREAKING: removed fetchData()' with no explanation of what replaced it is effectively a notice to abandon the project. For libraries and SDKs, major version bumps without migration guides directly translate to production outages when users upgrade: the old code fails, the new code is unknown, and the documentation provides no bridge. iso-25010:2011 analysability requires that version transitions be documentable without source inspection.

Why this severity: High because missing migration guides force users to discover breaking changes at runtime rather than upgrade time, turning routine version bumps into production incidents for every downstream integrator.

No changelog means users have no reliable way to know what changed between versions, whether a bug they hit is fixed, or whether upgrading is safe. A changelog that stops at v1.2.0 when the project is now on v2.1.0 is a signal that the project is poorly maintained — the same signal that drives dependency abandonment decisions. iso-25010:2011 analysability covers this: a project where change history is opaque requires source-level investigation to understand its evolution. Following Keep a Changelog format provides a predictable structure that users can parse quickly for the entries that matter to them.

Why this severity: Medium because the absence of a changelog doesn't block initial use but degrades confidence in the project's maintenance posture and makes upgrade decisions opaque, compounding over time.

A missing `LICENSE` file means the code is, by default, all rights reserved — no one can legally use, fork, distribute, or embed it in their product. Enterprise legal teams explicitly block adoption of unlicensed code, and many package registries and distribution channels will flag or reject it. A mismatch between `LICENSE` (MIT) and `package.json` `license` field (ISC) also creates legal ambiguity that blocks commercial use until resolved.

Why this severity: Low because unlicensed code blocks commercial adoption but has no runtime or security impact.

Documentation that isn't validated in CI can rot silently: links break, code examples go stale, and the docs site fails to build — all without anyone noticing until a user reports it. iso-25010:2011 reliability.maintainability measures exactly this: a project where documentation quality is not continuously verified is a project where documentation quality will degrade over time. For vibe-coded projects that ship quickly and update frequently, undiscovered documentation rot is the rule, not the exception. A single markdown-link-check step in CI catches broken links before they reach users.

Why this severity: Info because broken documentation validation doesn't affect runtime behavior, but it signals a maintenance posture that allows documentation quality to degrade silently across all future changes.