Topic
The decision-makers kept the legacy layout, against my recommendation. But a veto on the form layer doesn’t reach the others. Separation of concerns let me improve the boilerplate prose and the way structured data: phone numbers: is presented, without touching the page the deciders wanted left alone.
DITA XML can shrink the volume a technical writer creates, translates, and maintains: and a firewall vendor once got its documentation praised by the press because of it. But the productivity comes with a complexity bill. Here’s where structured authoring earns its keep, and where it’s overkill.
A growing engine-oil catalog — brands, viscosities, prices — becomes a maintenance nightmare as a Markdown table and a verbose tangle as DITA XML. One YAML file holds each fact once and generates every table, doc page, and app view from it.
