Documentation quality: docs-as-code and technical writing

This site is the working example. Every page is a Markdown file in Git, reviewed through pull requests, built by CI/CD, and deployed automatically. Documentation is part of the engineering system, not a by-product of it. Capability guides, architecture decisions, and research notes go through the same controls as production code.

That is deliberate. Across 25 years of engineering leadership in banking and financial services, documentation has proven to be the most undervalued capability in software engineering. Teams build complex systems and then lose institutional knowledge when three senior engineers leave in the same quarter. Multi-million-dollar platform investments fail because the onboarding documentation is a two-year-old Confluence page that no longer matches reality. In a regulatory examination, the auditor's question is simple, "how does this system work?", and the engineering team cannot produce a coherent answer. Documentation holds an engineering organisation together. During the DevSecOps transformation at a Tier-1 bank, documentation was treated with the same seriousness as automated testing: if it is not documented, it does not exist.

Why documentation quality matters

Good documentation supports knowledge sharing, onboarding, and incident response. In regulated environments it is also evidence that processes are defined, controls are implemented, and decisions are traceable.

Benefits

• Engineers can understand the architecture, design decisions, and operational procedures without relying on tribal knowledge.
• Well-documented systems need fewer "how does this work?" interruptions. Every hour spent on documentation saves dozens of hours of ad-hoc explanations.
• New team members become productive sooner. In banking, where onboarding involves security clearances and compliance training, cutting technical onboarding from months to weeks is a significant competitive advantage.
• When auditors ask how a system works, the answer is a link to a living document rather than a scramble to reconstruct knowledge from memory and Slack threads.

The Diataxis framework

Daniele Procida's Diataxis framework is the most useful structural model available for organising technical documentation. It identifies four documentation types, each serving a different user need:

Documentation Type	Purpose	User Need	Analogy
Tutorials	Learning-oriented	"I want to learn"	Teaching a child to cook
How-To Guides	Task-oriented	"I want to accomplish something"	A recipe in a cookbook
Reference	Information-oriented	"I want to look something up"	An encyclopedia article
Explanation	Understanding-oriented	"I want to understand why"	An article on culinary history

Diataxis prevents the common failure mode: documentation that tries to be everything at once and does none of it well. A tutorial that constantly interrupts the learning flow with reference details is a poor tutorial and a poor reference. A how-to guide that opens with a lengthy explanation of the underlying theory loses the reader who just needs to accomplish a task.

Applying Diataxis to this site

This site follows the model:

• Tutorials: the capability guides (DevSecOps Engineering, AI Engineering) are learning-oriented introductions to each domain.
• How-to guides: practice pages such as Fast Feedback and Database Change Management provide task-oriented guidance for implementing capabilities.
• Reference: the Architecture document and DORA Metrics page are lookup material for specific facts and specifications.
• Explanation: the research pages (AI Research, DevSecOps Research) and narrative sections provide the "why" behind the practices: theory, evidence, and reasoning.

Example: Diataxis in banking documentation

At the bank, we restructured the DevSecOps capability documentation using the Diataxis framework:

• Tutorial: "Getting Started with the Golden Path Pipeline", a step-by-step walkthrough for a new team onboarding to the platform.
• How-to guide: "How to Add SAST Scanning to Your Pipeline", a focused procedure for a specific task.
• Reference: "Pipeline Stage Reference", a complete listing of available stages, their parameters, and their SLAs.
• Explanation: "Why We Chose SAST over DAST as the Default Security Gate", an architecture decision record explaining the reasoning.

Before the restructuring, all four types of content were mixed together in a single Confluence space. Engineers could not find what they needed, gave up, and asked a colleague instead. After, self-service documentation resolution rates increased measurably and the "how do I...?" questions in Slack dropped significantly.

Docs-as-Code

The docs-as-code approach treats documentation with the same rigour and tooling as source code. Anne Gentle's Docs Like Code (2017) formalised a practice that had been emerging in open-source communities for years. The core principles:

• Version control: documentation lives in Git alongside the code it describes. Changes are tracked, authors are identified, and history is preserved.
• Review process: documentation changes go through pull requests with peer review. Code review catches bugs; documentation review catches inaccuracies, ambiguities, and gaps.
• Automated builds: the CI/CD pipeline builds and deploys the documentation, catching broken links, missing images, and build errors before publication.
• Continuous deployment: documentation is published automatically when changes merge to the main branch, so no manual "publish" step creates lag between reality and documentation.
• Plain text formats: documentation is written in Markdown, reStructuredText, or AsciiDoc, formats that diff cleanly, merge without conflict, and render across platforms.

How this site implements docs-as-code

This site implements docs-as-code directly:

• Repository: the entire site is a Git repository. Every page, image, and configuration file is version controlled.
• Framework: built with Docusaurus, a React-based static site generator designed for documentation, providing navigation, search, versioning, and responsive design out of the box.
• Content format: Markdown with YAML frontmatter, avoiding proprietary formats and lock-in.
• Diagrams: architecture diagrams are written in Mermaid, a text-based diagramming language that renders at build time. Diagrams are version controlled and diffable, unlike images from drawing tools.
• Build and deploy: every push to the main branch triggers a rebuild and deployment automatically.

Example: why not Confluence?

At the bank, the default documentation platform was Confluence. Everyone used it, and documentation quality was consistently poor. The reasons were structural:

1. No review process. Anyone could edit any page at any time, without a pull request, peer review, or quality gate.
2. No version control. Confluence has page history, but no branching, diffing, or merging. You cannot review a documentation change before it is published.
3. No build step. Nothing checked for broken links, outdated content, or formatting consistency.
4. Disconnected from code. Documentation lived in a separate system from the code it described. When the code changed, the documentation did not, because nobody remembered to update it.
5. Unreliable search. Finding the right page in a large Confluence space was frustrating enough that engineers defaulted to asking colleagues instead.

Docs-as-code solves all of this by applying to documentation the practices that already make code development reliable: version control, review, automation, and continuous deployment.

Clear writing

Clear writing keeps documentation readable and understandable. The Write the Docs community has documented extensive best practices, but the core ones are consistent:

• Concise language: use simple words to convey information. Avoid jargon unless your audience is guaranteed to understand it. Define acronyms on first use.
• Consistent terminology: if you call it a "pipeline" in one document, do not call it a "workflow" in another.
• Active voice: write "The pipeline runs the tests" rather than "The tests are run by the pipeline".
• Proper formatting: use headings, bullet points, code blocks, tables, and diagrams to organise content. A wall of unformatted text deters readers.
• Audience awareness: write for your actual audience, not a hypothetical one. A guide for senior engineers can assume different knowledge than a guide for graduate developers.

Thorough explanations

Thorough explanations give detailed information about the system and its components:

• Coverage: all aspects of the system, including its architecture, components, workflows, failure modes, and operational procedures.
• Step-by-step instructions: numbered steps for common tasks, with expected output at each step so the reader can verify they are on track.
• Examples: concrete examples illustrate concepts and demonstrate functionality better than abstract descriptions.
• Edge cases and failure modes: document what happens when things go wrong. In banking systems, the failure modes often matter more than the happy path.

Regular updates

Regular updates keep documentation accurate. Stale documentation is worse than no documentation, because it actively misleads:

• Version control: track documentation changes with the same branching and review practices as code.
• Review and approval: at minimum, every documentation change is reviewed by someone other than the author.
• Feedback mechanisms: collect feedback from users to find weak spots, from a simple "Was this page helpful?" link to periodic documentation health reviews.
• Documentation debt tracking: track pages that are known to be outdated, incomplete, or inaccurate, just as you track technical debt in code. Make documentation debt visible and allocate time to address it.

Example: documentation reviews as a sprint activity

At the bank, we added "documentation review" as a recurring sprint activity. Every two weeks, the team reviewed one section of the documentation for accuracy, completeness, and clarity, and implemented the resulting updates as pull requests in the same sprint. Documentation stayed within two weeks of reality, a large improvement over the previous state, where some pages had not been updated in over a year.

Example: catching drift with Claude Code

This site's own documentation review turned up exactly the failure mode described earlier. One page asserted specific numbers for the OpenClaw system's cron jobs and installed skills; a different page, and the system's own live telemetry, told a different story. Neither page was lying on purpose. They had simply drifted independently since whichever one was written last. Running Claude Code across the repository, with instructions to cross-reference every doc's factual claims against the live data sources they described, caught the contradiction in minutes. A human reviewer would have had to notice the same fact stated three different ways in three different files. The fix, in each case, was to stop hardcoding a number that changes and point to the live source of truth instead. This is the concrete version of documentation debt tracking: an agent that reads the whole repository at once is well suited to finding cross-file drift that a page-by-page review misses.

Examples of high-quality documentation

• API documentation: endpoints, parameters, response formats, error codes, and authentication requirements. The OpenAPI/Swagger specification provides a machine-readable standard that can generate interactive documentation automatically.
• User guides: step-by-step instructions for using the system, following the Diataxis "How-To Guide" pattern.
• Developer guides: coverage of the system's architecture, components, design decisions, and contribution guidelines.
• Runbooks: operational documentation describing how to respond to specific incidents or perform maintenance tasks. In banking, runbooks are a regulatory expectation.
• Architecture decision records: lightweight documents capturing the context, decision, and consequences of significant architectural choices. Michael Nygard's ADR format is the industry standard.

References

1. Gentle, A. (2017). Docs Like Code. Just Write Click. The practical guide to treating documentation as code, covering version control, review processes, automation, and publishing workflows for technical documentation.

2. Procida, D. (2017). "Diataxis: A Systematic Framework for Technical Documentation." Available at diataxis.fr. The Diataxis framework, which identifies four distinct documentation types (tutorials, how-to guides, reference, explanation) and provides guidance on when and how to use each.

3. Write the Docs Community. "Documentation Guide." Available at writethedocs.org/guide. A comprehensive community-maintained guide to documentation best practices, covering writing style, tooling, and organisational practices.

4. Nygard, M. (2011). "Documenting Architecture Decisions." Available at cognitect.com/blog/2011/11/15/documenting-architecture-decisions. The original Architecture Decision Record (ADR) format, which has become an industry standard for capturing the context and reasoning behind architectural choices.

5. Forsgren, N., Humble, J., & Kim, G. (2018). Accelerate: The Science of Lean Software and DevOps. IT Revolution Press. The DORA research identifies documentation quality as a factor in software delivery performance, particularly in its relationship to onboarding speed and operational reliability.

6. Google Technical Writing Courses. Available at developers.google.com/tech-writing. Free, practical courses on technical writing fundamentals, covering grammar, clarity, structure, and audience analysis.