Structured Authoring
Orchestrator manual
Demonstration piece. Shipped client documentation is under NDA, so this was built to the same standard instead.
Every task ends with a check and a stated expected result.
The sampleOpen Orchestrator installation and maintenance manual- Problem
- Software installation documentation with none of the discipline that safety-critical documentation takes for granted.
- Insight
- You can take the discipline out of S1000D without taking the schema: write the rules down, then hold to them, so review becomes a check rather than an argument about taste.
- Result
- A modular manual with a defined advisory hierarchy, eight stated writing rules, and verification built into every task.
The full story
Aerospace documentation standards carry a discipline most software manuals never adopt: a formal advisory hierarchy with written definitions, controlled vocabulary, one action per step, and a verification step that tells the reader whether the procedure worked. None of that requires the S1000D schema. All of it requires deciding the rules in advance and then holding to them.
This manual states its rules in the front matter and then obeys them. Eight writing rules, listed so a reviewer can check compliance rather than debate taste. Three advisory levels, each with a definition. Modules that are complete on their own, because a reader who arrives from a search result has not read what came before.
The part that required the most care was the advisory hierarchy. The aerospace convention reserves WARNING for risk of injury or death, and that definition does not transfer honestly to a server installation. Rather than quietly redefining it and hoping nobody noticed, the manual redefines the levels for this domain and states that it has done so. What is preserved is the property that matters: a WARNING never appears for something merely inconvenient, because a hierarchy whose top level is used loosely teaches readers to skip it.
Key decisions
- Adopt the discipline of S1000D without claiming the standard. Saying "informed by" where the schema is not used is the difference between a credible claim and one that collapses on the first specific question.
- Place every advisory before the step it applies to. An advisory read after the action is a post-mortem, and revision C moved them throughout the manual, not only where the problem had been noticed.
- End every task with verification and a stated expected result. A procedure the reader cannot confirm is a procedure whose failures surface later, in a different module, as a symptom nobody can trace back.
- Organize troubleshooting by symptom and order the causes by support case volume, not by severity. The reader has an observation, not a diagnosis, and the first cause listed should be the most common answer.
What it taught me
Publishing the rules in the front matter means every step can be checked against them, including by someone looking for a reason to disagree. That is uncomfortable and it is the reason to do it. Rules that stay in the writer's head leave when the writer does.