Documentation is Code for Humans

Ninety percent of developers skip your introduction and head straight for the README.md code samples. If those samples do not work, your documentation does not exist. Documentation is not prose; it is a user interface for your API.

We see this pattern across thousands of repositories we analyze at git11. Projects with high contributor retention share a specific trait. They treat documentation as a technical debt problem rather than a marketing task.

Good documentation minimizes the distance between a question and an answer. Every sentence that does not remove a barrier to entry is friction. You must optimize for the developer who is under a deadline and irritable.

The README Constraint

Your README.md is the front door of your project. It should fit on two screens. If a developer has to scroll six times to find the installation command, you have already lost them.

Follow this structure for every root readme:

• A one-sentence description of what the tool does.
• A three-line installation block using npm, pip, or cargo.
• A 10-line code snippet showing the most common use case.
• A link to the full API reference.

Avoid high-level philosophy in the readme. Developers care about inputs and outputs, not your vision for the future. Use the word "you" to describe actions the user takes.

Density and Utility

Word count is a liability. A 50-page manual is harder to maintain and harder to read than a 5-page cheat sheet. High-utility documentation uses tables, lists, and code blocks instead of paragraphs.

Use Reference Documentation for facts. This includes parameter types, return values, and error codes. This content should be generated from your code using tools like Swagger, TypeDoc, or Sphinx.

Use Tutorials for workflows. A tutorial should guide a user from a blank terminal to a running service in under five minutes. If your setup takes longer, your problem is not the documentation; it is your CLI design.

Versioning and Drift

Documentation that is 10% wrong is 100% useless. When a developer encounters an outdated config.yaml example, they lose trust in the entire document. They will stop reading and go to StackOverflow.

Link your documentation lifecycle to your CI/CD pipeline. Use doctest or similar tools to execute the code samples in your markdown files during every build. If the code fails, the build fails.

We recommend keeping documentation in the same repository as the code. Separate documentation sites often drift because developers forget to update a different repo after a PR. Use a /docs folder and a static site generator like Docusaurus or MkDocs.

Information Architecture

Developers do not read documentation linearly. They land on a page from a Google search or an IDE hover state. Every page must function as an entry point.

1. Use descriptive headers that contain keywords. 2. Place a table of contents at the top of long pages.

1. Include a search bar that indexes the entire site. 4. Link back to the source code for complex logic.

State the prerequisites at the top of every guide. If a user needs Node.js v18 or a specific API key, tell them in the first paragraph. Do not let them reach step five before realizing they have the wrong environment.

The Rule of Examples

Examples must be copy-pasteable. If you use placeholders like <YOUR_API_KEY>, make it obvious. Never use foo or bar in examples; use realistic data like user_id_12345 or prod_db_instance.

Break large examples into chunks. Explain why each line exists. If you are showing an authentication flow, do not just show the POST request. Show how to handle the 401 Unauthorized response.

Code comments inside examples should explain the "why," not the "what." The code already shows what is happening. Use comments to point out non-obvious side effects or performance trade-offs.

Formatting Standards

Consistent formatting reduces cognitive load. If you use backticks for file_names on one page, do not use italics for them on the next. Pick a style guide and enforce it with a linter like markdownlint.

• Files and directories: src/main.rs
• CLI commands: git checkout -b feature
• Environment variables: DATABASE_URL
• UI elements: Settings > Security

Use bold text for emphasis sparingly. If everything is bold, nothing is bold. Use it to highlight breaking changes or critical security warnings.

Maintenance as a Metric

Treat documentation fixes with the same priority as bug fixes. If a user opens a GitHub issue about a confusing paragraph, that is a documentation bug. Assign it to the engineer who wrote the feature.

Measure the effectiveness of your docs. Track which pages have the highest bounce rates. If users spend three seconds on a 2,000-word "Concepts" page and then leave, that page is failing to provide value.

Delete documentation that is no longer relevant. Every page you delete is one less page you have to update when you refactor your API. Aggressive pruning keeps the signal-to-noise ratio high.

Writing for the LLM

In 2024, half of your "readers" are Large Language Models. AI agents use your documentation to generate code for your users. Clear, structured text helps these models provide better answers.

Use clear semantic HTML tags or Markdown headers. Provide JSON schemas for your configuration files. When your documentation is machine-readable, your users get better results from their IDE copilots.

Avoid idiomatic language or complex metaphors. They do not translate well for international developers or for LLMs. Stick to simple, declarative sentences. This is not the place for personal flair.

Search and Discovery

The best documentation is the documentation that appears exactly when the developer needs it. Use docstrings that show up in IDE tooltips. Use descriptive error messages that include a URL to the relevant documentation page.

When a function throws an error, the error message should say: "Invalid input: x. See https://docs.example.com/errors#invalid-x for how to fix this." Help the user help themselves.

If you have a large project, categorize your documentation by user intent. There are four types of documentation: tutorials (learning), how-to guides (problem-solving), reference materials (facts), and explanations (context).

Final Evaluation

Before you publish a page, ask yourself if a junior engineer could follow it without asking you a question on Slack. If the answer is no, the documentation is not finished.

Effective documentation is a competitive advantage. It reduces support tickets and speeds up onboarding. It is the highest- work an engineer can perform.

Write documentation that solves problems rather than describing features.