Don't Panic: Structured Authoring for Documentation

Structured authoring gives documentation named parts and rules for connecting them. A warning stays a warning whether it appears on a web page or in a PDF. Its meaning travels with the content. Its appearance can change at the destination without requiring someone to rewrite the warning.

The problem starts when the same explanation lives in several guides. One copy gets corrected. Another retains yesterday's facts. A third acquires a product name that no longer belongs there. Single-source publishing maintains shared material once and derives several deliverables from it. There are still several guides to inspect. The maintenance points are fewer; the consequences of a shared edit can be wider.

The next idea is the topic, a unit with one coherent purpose. Explaining how connections work is different from telling someone how to connect an appliance. Both differ from listing accepted settings. Those pieces can sit together in a guide without becoming one inseparable object. Dividing them by reader question is more useful than dividing them at every page break.

Then comes the assembly, the selection and organization that turns pieces into a publication. A user guide and an administrator guide can share the connection explanation. Only the administrator guide needs credential rotation. The shared topic does not have to decide where it sits in every guide that uses it.

DITA makes this arrangement explicit with XML topics and maps. A map organizes topics and supplies context for named bindings. A content reference inserts shared material. A cross-reference links to material. Mixing those operations up can produce a perfectly respectable link where the reader needed an actual warning. The punctuation looks small; the missing instruction is larger.

Other approaches express structure differently. DocBook begins naturally with technical documents and their hierarchy. AsciiDoc uses semantic plain text, named attributes, includes, and conditional directives. Its includes import lines before parsing. Shared text still needs to make sense where it lands. Reuse is not a certificate of universal suitability.

The surprise is that valid markup can deliver an incomplete guide. A variant profile can remove a prerequisite. A reused topic can link to something absent from the smaller publication. A schema checks structural rules, not whether a reader can complete the task. Output review supplies evidence that source validation cannot provide.

Start with the Intro for the publishing path and vocabulary. Use the Cheatsheet when the difference between content references, keys, and profiles becomes slippery. The Exercise models two guides and tests a shared edit without installing a publishing engine. Field Notes covers conversion and localization costs. The Reference path then leads into actual authoring and publishing tools. One useful slice of content is enough to begin testing the model; a whole documentation migration can wait until that slice behaves.