OneDoc for Technical Documentation

Content owner: orlando.pereira@roche.com
OneDoc is the recommended framework for technical documentation in the CS CoE.

For teams creating architecture documentation, developer documentation, technical guidance, or other long-lived engineering content, OneDoc should be the default choice. It provides a documentation-as-code approach that improves quality, maintainability, reuse, and long-term accessibility.

This page summarizes why OneDoc is recommended. For implementation details, setup guidance, conventions, and examples, refer to the official OneDoc resources instead of duplicating that material here.

Recommendation

Use OneDoc by default for technical documentation in the CS CoE unless there is a clear and justified reason to use another approach.

This applies in particular to:

  • architecture documentation

  • developer documentation

  • technical playbooks and guidance

  • operational runbooks

  • product and platform documentation

  • documentation that must evolve together with code, services, or data products

Why OneDoc

OneDoc is recommended because it supports documentation that is easier to govern, easier to maintain, and more valuable over time.

FAIR-aligned documentation

OneDoc is built around the goal of FAIR documentation: documentation that is findable, accessible, interoperable, and reusable. This is especially important for technical knowledge that must remain discoverable and useful beyond the lifetime of a single tool, team, or project.

Documentation as code

OneDoc treats documentation like source code. Content is written in plain text, versioned in Git, reviewed collaboratively, and built through automation. This improves traceability, change control, and integration with normal engineering workflows.

Single-source, multi-format publishing

OneDoc enables teams to maintain documentation from a single source while generating multiple output formats and deployment targets. This reduces duplication and helps keep content aligned across channels.

Separation of content from presentation

Authors can focus on technical substance instead of formatting. Presentation, navigation, and styling are handled consistently, which improves readability and reduces maintenance overhead.

Quality and automation by design

Automation supports repeatable builds, quality checks, and continuous publishing. This helps documentation stay current, consistent, and easier to maintain as systems evolve.

Reuse and modularity

OneDoc supports modular documentation that can be reused across teams, products, and contexts. This reduces repeated effort and enables shared building blocks for common content.

Better collaboration across roles

Technical writers, architects, developers, maintainers, and subject-matter experts can all contribute using a workflow that fits engineering delivery rather than sitting outside it.

When OneDoc is a strong fit

OneDoc is particularly well suited when documentation must be:

  • versioned and reviewable

  • maintained alongside code or architecture assets

  • continuously updated through project delivery

  • reusable across teams or products

  • published consistently in web and document formats

  • preserved as a durable technical asset

Why this matters for CS CoE

Technical documentation is a strategic asset. When it is fragmented across disconnected tools or maintained manually, it becomes harder to find, harder to trust, and harder to reuse.

OneDoc helps address this by making documentation part of the delivery lifecycle. The result is documentation that is more sustainable, more consistent, and better aligned with the long-term knowledge needs of Roche and the CS CoE.

Questions or support

If you have questions about when or how to use OneDoc for architecture or technical documentation, contact the Architecture Team.