Contributing to this manual

Documentation is part of the EDD interface. A change to a CLI command, role, configuration default, state transition, stream format, sensor, output product, or operational recovery path is incomplete until its documentation is updated.

Build and check

$ python3 -m venv .venv
$ source .venv/bin/activate
$ python -m pip install --requirement requirements-docs.txt
$ make strict
$ make linkcheck

make strict treats Sphinx warnings as errors. Link checking is separate because it requires external network access and some observatory links may be private.

Writing rules

  • Start a page with the task or capability, not its implementation history.

  • State the core or plugin version against which reference material was checked.

  • Mark units, accepted values, defaults, constraints, and production safety.

  • Use complete examples that agree across role name, container name, product ID, and stream references.

  • Distinguish KATCP wire names with hyphens from Python method names with underscores.

  • Do not make autodoc output the primary user documentation. Generated API reference may supplement a narrative contract.

  • Do not include credentials, real tokens, private keys, or vault ciphertext.

  • Prefer stable public links and explain when a referenced service is internal.

Plugin page checklist

Every plugin page should cover:

  1. purpose and supported observing modes;

  2. collection version and fully qualified roles;

  3. pipeline flavour and lifecycle differences;

  4. input and output stream formats;

  5. normal, expert, and debug configuration;

  6. hardware, network, storage, and external dependencies;

  7. scan metadata and output products;

  8. sensors, dashboards, logs, and healthy behaviour;

  9. a realistic provision example;

  10. common failure modes; and

  11. unit, lifecycle, and provision tests.

Review

Test procedural documentation by following it from a clean environment. Review operator pages with an operator, site deployment pages with an administrator, and plugin reference with the plugin maintainer. Record the verified version in the same change.