Skip to content

Topic: Technical Writing

Three levels of technical documentation: wasteland, English garden, French garden

Technical documentation is like a garden, and it grows in three stages. The wasteland has no process and no owner. The English garden is cultivated but informal. The French garden is structured and deliberate. Knowing which one you’re standing in tells you what to fix next: and what not to.

Olivier Carrère3 min read

View as Markdown
On this page ▼

Why does technical documentation quality stall despite heavy investments in new authoring tools? Evaluating content maturity requires mapping documentation systems onto three gardening archetypes: the unmanaged wasteland, the cultivated English garden, and the strictly structured French garden.

Enters content maturity mapping. Document quality depends on three synchronized factors: process, team ownership, and semantic content format.

1 · Wasteland

Process
No process
Team ownership
No owner
Content format
Inconsistent formats

2 · English garden

Process
Reliable process
Team ownership
Dedicated team
Content format
Consistent but unstructured format

3 · French garden

Process
Reliable process
Team ownership
Dedicated team
Content format
Structured, semantic format (DocBook, DITA)

Wasteland architecture

Unmanaged documentation lacks assigned ownership and standardized workflows. Authors produce disconnected files across arbitrary formats: a Word document in one folder, an unmaintained wiki page in another, and static PDFs exported years ago.

Wasteland ≠ bad writing: A wasteland isn’t defined by poor writing.

Accidental quality occurs when an engineer writes a clear guide during downtime. Without formal maintenance processes, single pages decay when products update.

Topic-based English gardens

An English garden introduces dedicated ownership and consistent authoring workflows. Content team members maintain unstructured or lightweight topics using predictable tools.

Cultivating topic-based content provides reliable user documentation without XML schema complexity. Maintaining unstructured Markdown files in Git repositories delivers high accuracy without structured authoring overhead.

Often enough on its own: For many teams, a well-maintained English garden is already far enough.

Structured French gardens

A French garden introduces strict semantic constraints: content elements conform to rigid DITA or DocBook schemas rather than desktop publishing layouts.

Cartoon: Louis XIV in ornate fleur-de-lys robes wades knee-deep through a reedy marsh, asking a gardener 'Must we pass through the English phase to reach the French one?' The gardener, in a straw hat, holds a rolled formal garden plan and pruning shears; a palace like Versailles rises under construction behind them.
The Sun King wants the French garden’s deliberate order and would rather skip the informal English garden on the way: but the levels are climbed in turn, and for many teams the English garden is already far enough.

Separating semantic payloads (warnings, prerequisites, steps) from presentation stylesheets allows automated single-source publishing across multiple languages and channels.

  1. Semantic payloads (warnings, prerequisites, steps)
  2. Presentation stylesheets
  3. Multiple languages & channels

Component interdependence

Adopting structured DITA schemas without establishing process discipline creates an expensive XML wasteland. Each maturity level requires alignment across all three pillars, as the matrix above shows:

DITA schema + weak process or ownership → an expensive XML wasteland.
Process, ownership, and semantic structure rising together → structured publishing that works.

Maturity diagnostics

Diagnostic evaluation prevents premature migration to complex schemas:

  1. Establish process and ownership. Teams in a wasteland must do this before changing markup formats.
  2. Run a content audit. Measure current reuse requirements before committing to a DITA XML migration.

External sources

Hero image: “The Ingenious Cottage Garden at Chatsworth, Derbyshire” by UGArdener, licensed under CC BY-NC 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

    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.

    2 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

Back to all articles