Skip to content

Topic: Docs-as-Code

A frozen layout doesn’t freeze the content: working under a design veto

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.

Olivier Carrère2 min read

View as Markdown
On this page ▼

Does a design layout veto prevent content and data improvements across a publishing pipeline? When stakeholders freeze legacy page layouts, tangled document templates lock prose and data edits.

Enters layer-isolated architecture. Separating templates, editorial prose, and structured YAML data restricts design vetoes strictly to the visual presentation layer.

Organizational design constraints

Stakeholders frequently refuse visual layout updates to maintain audience familiarity. In tangled authoring systems, visual layout freezes prevent prose edits because typography and text live in single files.

Decoupling layout templates from data sources confines design constraints strictly to visual geometry.

Layer isolation scope

Decoupling authoring layers isolates visual vetoes:

LayerStatus under the vetoWhat I did with it
Form (template, geometry)Frozen by decisionUntouched: exactly as required
Boilerplate content (editorial prose)FreeClarified terminology, active voice, inclusive glosses
Data (facts: dates, contacts, prices)FreeCorrected a dead URL, normalized phone numbers
Generation (the script)FreeAdded per-language phone formatting

Visual templates remain frozen while underlying content and data layers continue to evolve.

Layer isolation scope Diagram

Form
template, geometry

Boilerplate content
editorial prose

Data
dates, contacts, prices

Generation
the script

Published document

Figure 1 — Layer isolation scope workflow diagram.

The veto stops at one box. The other three keep moving.

Content layer modifications

Updating explanatory text surrounding calendar grids improves clarity without altering visual column geometry:

  • Inclusive glosses: Adding explicit parenthetical definitions for internal jargon.
  • Active voice: Converting passive descriptions into direct procedural instructions.
  • Term normalization: Standardizing section headings and terminology across chapters.

Text reflows cleanly inside predefined template boundaries.

Data presentation rules

Single-sourced phone numbers format dynamically based on target audience locales:

Number’s home countryFrench editionEnglish editionSpanish edition
Francenational (0X …)+33 …+33 …
Spain+34 …+34 …national
Québec (Canada)+1 …+1 …+1 …

Generation scripts format single YAML data entries for international audiences at build time without modifying underlying templates.

Decoupling form, content, and data protects ongoing editorial improvements from design disagreements. The next step is adding automated regression checks to verify that content edits never exceed frozen template layout boundaries.

Key takeaways

External sources

Hero image: “Dutch Countryside Farm old Gate” by Sabeel Media, licensed under CC BY-NC-SA 2.0.

Continue reading

All articles
  • DITA XML

    Structured authoring’s hidden bill: when DITA XML pays off, and when it doesn’t

    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.

    3 min read

  • Docs-as-Code

    Why hand-maintained InDesign files rot — and what docs-as-code does instead

    A 370-cell calendar that shifts every year. A lead’s name in three places. An IBAN in an invisible text box. These are not unusual InDesign problems — they are what InDesign files become when they accumulate facts with no single home. Two projects show what the alternative looks like — and where InDesign’s own global tools stop short.

    15 min read

  • Docs-as-Code

    CI/CD for a print artifact: one principle, two projects

    Running make locally is one thing. Guaranteeing that every contributor’s push or YAML edit on GitHub produces the same press-ready artifact on a clean machine with a pinned toolchain is another. How two print projects implement that guarantee with GitHub Actions.

    12 min read