Documentation Quality: Docs-as-Code and the Art of Technical Writing

You are reading the proof. This site — the one you are on right now — is a Docusaurus documentation site where every page is a Markdown file stored in a Git repository, reviewed through pull requests, built by a CI/CD pipeline, and deployed automatically. The documentation is not a by-product of the engineering work. It is the engineering work. Every capability guide, architecture decision, and research synthesis published here went through the same rigour as production code: version-controlled, peer-reviewed, and continuously improved.

This is not an accident. 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 extraordinary systems and then lose all 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 regulatory examinations, the auditor's question is simple — "how does this system work?" — and the engineering team cannot produce a coherent answer. Documentation is not overhead. It is the connective tissue that 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

High-quality documentation is crucial for knowledge sharing, onboarding, and troubleshooting. In regulated environments, documentation also serves as evidence — evidence that processes are defined, controls are implemented, and decisions are traceable.

Benefits

• Improved Understanding of the System: Engineers can comprehend the architecture, design decisions, and operational procedures without relying on tribal knowledge.
• Reduced Time Spent on Support and Maintenance: Well-documented systems require fewer "how does this work?" interruptions. Every hour spent on documentation saves dozens of hours of ad-hoc explanations.
• Increased Developer Productivity: New team members become productive faster. In banking, where onboarding involves security clearances and compliance training, reducing the technical onboarding time from months to weeks is a significant competitive advantage.
• Regulatory Readiness: When auditors ask how a system works, the answer is a link to a living document, not a frantic scramble to reconstruct knowledge from memory and Slack threads.

The Diataxis Framework

Daniele Procida's Diataxis framework provides the most useful structural model available for organising technical documentation. It identifies four distinct 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

The power of Diataxis is in what it prevents: the tendency to write documentation that tries to be everything at once and succeeds at nothing. A tutorial that constantly interrupts the learning flow with reference details is a poor tutorial and a poor reference. A how-to guide that begins with a lengthy explanation of the underlying theory will lose the reader who just needs to accomplish a task.

Applying Diataxis to This Site

This site itself follows the Diataxis model:

• Tutorials: The capability guides (DevSecOps Engineering, AI Engineering) serve as learning-oriented introductions to each domain.
• How-To Guides: Specific practice pages (Fast Feedback, Database Change Management) provide task-oriented guidance for implementing capabilities.
• Reference: The Architecture document and DORA Metrics page serve as reference material for looking up specific facts and specifications.
• Explanation: The Research pages (AI Research, DevSecOps Research) and narrative sections provide the "why" behind the practices — the 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 the restructuring, 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) formalized this practice, which had been emerging in open-source communities for years. The core principles are:

• 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. Just as code review catches bugs, documentation review catches inaccuracies, ambiguities, and gaps.
• Automated Building: Documentation is built and deployed by the CI/CD pipeline. Broken links, missing images, and build errors are caught before publication.
• Continuous Deployment: Documentation is published automatically when changes are merged to the main branch. There is no manual "publish" step that creates lag between reality and documentation.
• Plain Text Formats: Documentation is written in Markdown, reStructuredText, or AsciiDoc — plain text formats that diff cleanly, merge without conflict, and render across platforms.

How This Site Implements Docs-as-Code

This site is a concrete implementation of docs-as-code:

• Repository: The entire site is a Git repository. Every page, every image, every configuration file is version-controlled.
• Framework: Built with Docusaurus, a React-based static site generator designed for documentation. Docusaurus provides navigation, search, versioning, and responsive design out of the box.
• Content Format: All content is Markdown with YAML frontmatter. No proprietary formats, no 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 created in drawing tools.
• Build and Deploy: The site is built and deployed automatically. Every push to the main branch triggers a rebuild and deployment.

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. There was no pull request, no peer review, no quality gate.
2. No version control. Confluence has page history, but it does not support branching, diffing, or merging. You cannot review a documentation change before it is published.
3. No build step. There was no automated check 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. Search was unreliable. Finding the right page in a large Confluence space was an exercise in frustration. Engineers defaulted to asking colleagues rather than searching.

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

Clear Writing

Clear writing ensures that the documentation is easy to read and understand. The Write the Docs community has documented extensive best practices, but the core principles are simple:

• Concise Language: Use simple and concise language to convey information. Avoid jargon unless your audience is guaranteed to understand it. Define acronyms on first use.
• Consistent Terminology: Use consistent terminology throughout the documentation. If you call it a "pipeline" in one document, do not call it a "workflow" in another.
• Active Voice: Write in active voice ("The pipeline runs the tests") rather than passive voice ("The tests are run by the pipeline"). Active voice is clearer and more direct.
• Proper Formatting: Use headings, bullet points, code blocks, tables, and diagrams to organise content. A wall of unformatted text is not documentation — it is a deterrent.
• 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 provide detailed information about the system and its components:

• Comprehensive Coverage: Cover all aspects of the system, including its architecture, components, workflows, failure modes, and operational procedures.
• Step-by-Step Instructions: Provide step-by-step instructions for common tasks and procedures. Number the steps. Include expected output at each step so the reader can verify they are on track.
• Examples and Use Cases: Include examples and use cases to illustrate concepts and demonstrate functionality. Concrete examples are worth more than abstract descriptions.
• Edge Cases and Failure Modes: Document what happens when things go wrong. In banking systems, the failure modes are often more important than the happy path.

Regular Updates

Regular updates ensure that the documentation remains accurate and up-to-date. Stale documentation is worse than no documentation, because it actively misleads:

• Version Control: Using version control systems to track changes to the documentation, with the same branching and review practices as code.
• Review and Approval: Implementing a review and approval process for documentation updates. At minimum, every documentation change should be reviewed by one person other than the author.
• Feedback Mechanisms: Collecting feedback from users to identify areas for improvement. This can be as simple as a "Was this page helpful?" link or as structured as periodic documentation health reviews.
• Documentation Debt Tracking: Just as you track technical debt in code, track documentation debt — pages that are known to be outdated, incomplete, or inaccurate. 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. The review produced a list of updates, which were implemented as pull requests in the same sprint. This practice ensured that documentation stayed within two weeks of reality — a massive improvement over the previous state, where some pages had not been updated in over a year.

Examples of High-Quality Documentation

• API Documentation: Providing detailed information about APIs, including 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: Creating user guides that provide step-by-step instructions for using the system, following the Diataxis "How-To Guide" pattern.
• Developer Guides: Developing guides for developers that cover the system's architecture, components, design decisions, and contribution guidelines.
• Runbooks: Operational documentation that describes how to respond to specific incidents or perform specific maintenance tasks. In banking, runbooks are a regulatory expectation.
• Architecture Decision Records: Lightweight documents that capture 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.