Once-Only in Documentation

What is the Once-Only Principle?

The Once-Only principle states: Data or information should be captured, stored, and maintained only once – and reused at all relevant points. It avoids redundancy, minimizes sources of error, and reduces maintenance effort. Originally known from public administration and e-government, it is gaining increasing importance in technical documentation – especially in complex, agile, and scalable systems.

Why is Once-Only Important in Documentation?

In software projects, documentation often grows in an uncoordinated manner:

• API documentation exists separately from user manuals.
• Diagrams are drawn manually and not synchronized with the code.
• Configuration notes are duplicated across multiple documents.

This leads to inconsistencies, outdated content, and increased maintenance effort. Once-Only creates clarity here:

Write once. Use everywhere.

Documentation Engineering: The Foundation for Once-Only

Documentation Engineering is the systematic, engineering-based approach to documentation – with a focus on structure, reusability, and automation. It enables:

• Modular documents: Content is broken down into reusable building blocks (e.g., “component descriptions”, “error codes”).
• Central sources: All content originates from a single, maintained source (Single Source of Truth).
• Automated linking: Content is dynamically translated into various output formats (PDF, web, help systems).

Example: An API endpoint is described in a YAML file. This serves as the source for:

• Swagger/OpenAPI documentation
• User manual sections
• Developer reference
• Automated tests

→ No manual copying. No inconsistencies. Only one source.

Docs-as-Ecosystem: Documentation as a Living System

A Docs-as-Ecosystem understands documentation not as a static artifact, but as an integrated, dynamic system connected to code, tests, CI/CD, and monitoring.

Characteristics of a Docs-as-Ecosystem:

• Automatic generation: Documentation is generated from code comments, configuration files, or tests.
• Feedback loops: Users can provide feedback directly from the documentation – e.g., via “Was this information helpful?” buttons.
• Versioning: Documentation is versioned along with the code – no discrepancies between version 1.2 and its corresponding documentation.
• Searchability & navigation: Content is linked via search engines and intelligent navigation – not just readable linearly.

Impact on Once-Only: Every piece of content is part of a network. Changes in one place automatically affect all dependent documents – without manual follow-up maintenance.

Diagrams-as-Code: Visualizations as Code

Diagrams are often the biggest source of redundancy:

• An architecture diagram is created in PowerPoint, then inserted into Confluence, then copied into a PDF.
• When changes occur, it must be updated manually everywhere.

Solution: Diagrams-as-Code

With tools like Mermaid, PlantUML, Graphviz, or Diagrams.net (with code export), diagrams are defined as text – and can be integrated into the documentation.

Example (Mermaid):

graph TD
    A[User] --> B[API Gateway]
    B --> C[Auth Service]
    B --> D[Order Service]
    C --> E[DB]
    D --> E

→ This code can be embedded in Markdown, Sphinx, Docusaurus, or other systems. → Changes to the code automatically update the diagram in all documents. → No manual maintenance. No outdated graphics.

Docs-as-Code: The Technical Implementation of Once-Only

Docs-as-Code is the practice of treating documentation like software:

• Versioned in Git
• Automated with CI/CD
• Validated with tests
• Maintained with Pull Requests

Key elements:

• Source code repositories: Documentation resides in the same repo as the code – or in a dedicated but linked repo.
• Automated builds: With every change, the documentation is regenerated and published.
• Validation: Links are checked, syntax is validated, diagrams are rendered.
• Reusability: Using include or import mechanisms, building blocks are reused across multiple documents.

Example with Antora (AsciiDoc):

.. include::requirements.adoc

Changes to requirements.adoc affect all documents that include it.

Practical Implementation: Step-by-Step

1. Identify redundant content → Which sections are copied multiple times? Which diagrams exist in multiple versions?

2. Create central sources → Consolidate recurring content into reusable files (e.g., shared/, components/).

3. Choose tools that support Docs-as-Code and Diagrams-as-Code → Markdown + Mermaid (or AsciiDoc + PlantUML) + Git + CI/CD (e.g., GitHub Actions, GitLab CI).

4. Integrate documentation into the development process → Every code change affecting the API requires a documentation change – as part of the Pull Request.

5. Automate validation and publication → Check links, syntax, diagrams. Publish automatically to a documentation website.

6. Establish feedback mechanisms → Users can provide feedback directly from the documentation – e.g., via GitHub Issues or integrated forms.

Conclusion: Once-Only is Not a Luxury – It is Necessary

In a world where software is constantly growing and changing, manual documentation is no longer sustainable. Once-Only is the answer:

• Efficiency: Less work, fewer errors.
• Consistency: All users see the same, current state.
• Scalability: Documentation grows with the system – without additional effort.

With Documentation Engineering, Docs-as-Ecosystem, and Docs-as-Code, Once-Only becomes not only possible – it becomes the foundation of modern, living documentation.

• ←Previous
• Next→