Documentation as Engineering Performance

Developers spend 30% of their day reading reference material. Most of that time is wasted because the documentation attempts to teach instead of providing a path to a specific outcome. Engineering teams produce thousands of pages of text that lie dormant in docs/ folders while the actual knowledge lives in Slack threads and private DMs.

Good documentation is a search problem. You are writing for an engineer who has ten browser tabs open and a failing CI pipeline. They do not want a narrative. They want the specific environment variable name, the terminal command, or the JSON schema required to fix their immediate blockage.

The Minimum Viable Spec

Every repository must start with a README.md that answers three questions in the first 200 words. What does this code do? How do I run it locally? How do I deploy it? If a developer has to scroll to find the install command, you have failed.

• Use npm install or pip install -r requirements.txt as the first code block.
• List dependencies specifically, including versions like Node 18.x or Postgres 14.
• Provide a sample .env.example file in the root directory.
• Document the top three most common failure modes in a troubleshooting section.

Writing for developers is about cutting. Remove adjectives and adverbs. Instead of writing "This highly efficient utility ensures data consistency," write "This script syncs the production database to the staging environment."

Code Examples Above Text

Code is the primary language of documentation. Engineers scan for code blocks and skip the surrounding paragraphs. If your example requires the reader to refer back to three different paragraphs to understand the variables, delete it and rewrite.

1. Ensure every code block is copy-pasteable and runs without manual edits. 2. Use descriptive variable names in examples rather than foo or bar.

1. Add brief comments to the code to explain non-obvious logic. 4. Use a specific curl command for API documentation rather than a generic URL.

We see high-performing teams at git11 use automated tests to verify their code examples. If the code in your docs/ folder breaks when the API changes, the documentation is worse than useless. It is a trap. Link your documentation to your CI pipeline.

Structure for Discovery

Documentation should follow the Diátaxis framework. It divides content into four distinct categories based on user intent: tutorials, how-to guides, technical reference, and explanation. Mixing these categories creates friction for the reader.

• Tutorials are for beginners and follow a strict linear path with a guaranteed result.
• How-to guides solve specific problems for experienced users who know the basic terminology.
• Technical references provide a data-driven map of the internal API, functions, and classes.
• Explanations provide background context, architecture decisions, and historical reasons for a specific design.

Never put architecture diagrams in a how-to guide. A developer trying to fix a bug does not care about your high-level design philosophy. They care about an entry point. Keep the reference data in a separate REFERENCE.md or use tools like Swagger for APIs.

Contextual Metadata

Documentation decays at the same rate as code. Stale information is an engineering risk. Use metadata at the top of every document to establish authority and recency. This allows the reader to judge if the information is still valid given the current state of the system.

• Author: Senior Engineer who owns the module.
• Status: Stable, Draft, Deprecated, or Experimental.
• Last Verified: The date or git commit hash when the instructions were last tested.
• Audience: Frontend, DevOps, or Security personnel.

When we analyze repositories at git11, we find that the most useful internal docs are those updated at least once every six months. If a document hasn't been touched in a year, it should be marked with a prominent warning or archived in an archive/ directory to prevent it from appearing in search results.

Writing for the Grep

Engineers search for specific error codes, function names, and keywords. They do not search for concepts. Your headings must match the strings developers will actually type into a search bar. Use Handling 503 Errors instead of Resiliency Strategies.

• Include exact error messages in your troubleshooting sections.
• Use the full name of specialized libraries or internal tools.
• Avoid screenshots of text because they are not searchable and break over time.
• Link directly to the source code file on GitHub where the logic is defined.

Standardize your file structure across all repositories in your organization. If every project has a CONTRIBUTING.md and a DEPLOYMENT.md in the same relative location, engineers can find what they need without thinking. Predictability is more valuable than creativity in technical writing.

The Burden of Maintenance

Automation is the only way to keep documentation accurate at scale. Do not write by hand what can be generated from code. Use JSDoc, TypeDoc, or Sphinx to build reference pages directly from your source files. This ensures that when a function signature changes, the documentation changes with it.

1. Generate API documentation from your OpenAPI or GraphQL schema. 2. Use linters like markdownlint to enforce formatting consistency.

1. Implement a doc-check in your pull request template. 4. Treat doc updates as a blocking requirement for merging new features.

If you find yourself explaining the same concept three times in a Slack channel, that is a signal to update the documentation. Copy the answer you gave in Slack and paste it into the repo. The best documentation is often just a collection of curated answers to real questions.

Internal Project Onboarding

The most painful experience for a new engineer is their first week. A project should take no more than 30 minutes to set up. If the setup process takes a day, your documentation is the bottleneck. Trace the setup path yourself once a month to find where the instructions have drifted from reality.

• Provide a script called bin/setup that handles environment variables and dependencies.
• List common pitfalls for specific operating systems, especially macOS and Linux differences.
• Document where the logs are located and how to tails them.
• Give the user a small "first task" to verify their environment is functional.

Most teams omit the “why” behind their technical decisions. While the “how” is critical for daily tasks, the “why” prevents future engineers from reverting necessary fixes. Use Architecture Decision Records (ADR) in a dedicated docs/adr/ folder to capture these nuances.

Visuals and Diagrams

Only use diagrams when words fail to describe a complex flow. Avoid proprietary formats like Visio or binary files like JPEGs. Use text-based diagramming tools like Mermaid.js or PlantUML that can be stored in version control and rendered by GitHub directly.

• Represent data flow from left to right or top to bottom.
• Use standard notation for databases, queues, and external services.
• Keep diagrams small; a single diagram should focus on one subsystem.
• Label every arrow with the protocol used, such as gRPC, HTTPS, or AMQP.

A bad diagram is noisier than no diagram at all. If the diagram is out of sync with the code, delete it immediately. The goal is to provide a mental model, not a pixel-perfect representation of every network hop.

Feedback Loops

Documentation is a product. Treat it like one by collecting telemetry on it. If you host your docs on a platform like Docusaurus or GitBook, track which pages are visited most and which search terms return zero results. This tells you where your knowledge gaps are.

• Add a “Was this page helpful?” widget at the bottom of every section.
• Create a dedicated Slack channel for doc feedback.
• Allow anyone in the engineering team to submit a PR for a doc fix.
• Reward engineers who spend time improving the internal knowledge base during performance reviews.

Writing documentation is not a distraction from engineering. It is engineering. Code that nobody can use or maintain is a liability. You write docs to save your future self from answering the same question for the tenth time.

Optimize for the engineer who is tired, frustrated, and in a hurry.