| {row.type} |
- {row.name} |
{numberToWords(row.cylinders)}-cylinder engines |
{row.viscosity_grade} |
${row.price.toFixed(2)} |
```
*Notice:* A single 4-line change in the rendering component updates every table across your entire documentation site without touching a single record in `oil-types.yaml`.
---
### Growing with your YAML: The maturity model
What begins as a simple reference file can mature into a complete documentation asset pipeline:
Our **oil-types.yaml** file scales through four stages:
1. **Structured source:** The YAML file stores pure data facts once.
2. **Multi-channel distribution:** The file generates DITA reference topics, OpenAPI JSON endpoints, and dynamic web UI components.
3. **Strong typing:** Enforcing numeric types for prices (`float`) and cylinder counts (`int`) prevents formatting errors.
4. **Schema validation:** A central JSON Schema or Zod validator in your CI pipeline guarantees that missing fields or malformed records fail the build before reaching production.
---
## Why a structured source is better than embedded tables
Tables are an effective way to present structured data in a familiar, scannable layout. However, authoring user-facing tables directly in Markdown source files ties data to presentation.
A stronger alternative is to **extract data at build time from a structured source**, such as a YAML single source of truth. This approach allows you to **render the same information in multiple ways**, each tailored to the target medium and the specific needs of your audience: whether that’s a Markdown table in documentation, a JSON payload for an API, or a dynamic HTML component in a UI. See [how Astro exposes YAML data through a live API](https://redaction-technique.org/experimental-astro-api-docs) for a working example of this distribution pattern.
By decoupling data from presentation, you gain maintainability, consistency, and flexibility as your content grows.
---
## Where YAML wins, and where it doesn’t
The title of this post is deliberately bold, so it is essential to scope the architectural claim honestly. YAML outperforms the alternatives for one specific job: small-to-medium structured reference data that builds into a static site or feeds an API under Git.
Stretch it past that job and the comparison flips, because the alternatives are not strawmen; each is strong where YAML is weak:
Small-to-medium structured reference catalogs, product specs, configuration files, and multi-format generated outputs that require clean Git diffs and branch reviews.
Conceptual explanations, tutorials, guides, and thought leadership where content is paragraph-driven and adding a formal schema would introduce needless friction.
Large-scale documentation teams requiring strict structural enforcement, controlled vocabularies, content specialization, and formal schema validation across multi-division publications.
Datasets exceeding tens of thousands of records, arbitrary SQL queries, relational joins across tables, concurrent writes, and real-time updates that occur outside static site builds.
YAML also has real trade-offs and sharp edges that a fair architectural evaluation must acknowledge:
* **Indentation sensitivity:** A missing space can silently restructure an entire object hierarchy.
* **Boolean parsing traps:** In older YAML 1.1 parsers, strings like `yes`, `no`, `on`, and `off` can be coerced into booleans unless strictly quoted.
* **No built-in schema:** Unlike XML (which has native XSD/DTD validation), YAML requires an external schema validator (such as JSON Schema or Zod) to guarantee data integrity.
* **Scale limits:** Parsing a 50,000-row YAML file during build time is inefficient; flat files lack relational indexes and `JOIN` capabilities.
**The architectural verdict:** For small-to-medium structured reference data you want under Git and rendered many ways, YAML is the best-fit source of truth. It is not a universal replacement for prose or databases—it is a purpose-built lane for sustainable, docs-as-code reference information.
---
Learn more about [getting the benefits of DITA XML without its complexity](https://redaction-technique.org/strong-information-typing-without-xml-overhead). Modern docs-as-code workflows let technical writers structure information using lightweight, open tools. No XML headaches required.
## Related reading
- [Automatically insert data into a reStructuredText file](https://docs.redaction-technique.org/en/tutorials/auto-insert-data-restructuredtext/) - generating docs from a structured data source.
- [Automatically insert SQL data into a reStructuredText file](https://docs.redaction-technique.org/en/tutorials/auto-insert-sql-data-restructuredtext/) - the database-backed variant of the same idea.
## External sources
- [YAML language reference](https://yaml.org/)
- [Schema-based validation / strong typing](https://json-schema.org/)
- [OpenAPI: YAML as an API source of truth](https://www.openapis.org/)
*Hero image: ["Honeycomb"](https://www.flickr.com/photos/krayker/2268587409) by [Karunakar Rayker](https://www.flickr.com/photos/krayker/), licensed under [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/).*
---
Source: https://redaction-technique.org/scalable-maintainable-technical-docs-with-yaml