Style Guide
Implementation Guides are intended to be predominantly task-oriented “how-to” guides, as defined by the top-right quadrant of the Diataxis technical documentation framework, https://diataxis.fr/. Where the Implementation Guide also includes documentation represented by one of the other quadrants in the framework (e.g. understanding-oriented, explanatory documentation), this must exist as a separate section - or multiple separate sections - in the Implementation Guide.
The guidance below relates to the “how-to” parts of the Implementation Guide.
Overall Style
- The guide should be as terse as possible.
- The guide should not contain normative language.
- The guide should read like a recipe for how to implement the specification.
- Assume the reader is approaching from the angle of “I have a broadcast device/controller and now want to make it support NMOS”.
- Give examples.
- Identify gotchas.
References
- The guide should not simply repeat the specification.
- The guide can reference widely available resources to aid implementation (for instance nmos-cpp).
- Do not cut and paste from other sources; provide a reference instead.
- Do not regurgitate or attempt to paraphrase any passages from the AMWA specifications; reference the relevant passages instead.