Tag
Technical Writing
5 articles
-
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.
-
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.
-
Slow food for fast thinking: designing with cognitive ease in mind
What can Kahneman’s Systems 1 and 2 teach us about technical writing? This post explores how minimalism and DITA structure align with cognitive systems to make documentation more intuitive and human-centered.
-
What YAML gives technical docs that XML and Markdown can't
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.
-
Translating legacy French docs to English with DeepL and GPT-4o
Professionally translating hundreds of legacy French Markdown files would have cost a fortune. Instead, a DeepL-then-GPT-4o pipeline with Git diffs as a safety net: keep the good translations file by file, discard the rest, rebuild.