Style Guide

Use these conventions when writing or reviewing documentation. Keep explanations concise and close to the commands they explain. See Contributing for the contribution process.

Language and presentation

Use UK English, including licence, modelling and behaviour. Preserve the spelling of commands, paths, identifiers and upstream titles. Use descriptive headings, short paragraphs and lists where they make steps or choices easier to follow. Explain what users need to do without repeating the same guidance in several sections.

Commands, output and placeholders

Use te1st as the example username in commands, shell prompts and output. Replace real usernames consistently, including those in example file paths. Make clear which values readers must replace with their own username, paths or input filenames.

Use inline code for commands, paths, module names and environment variables. Use bash code blocks for scripts and commands that users can copy directly. Use console blocks when showing prompts and command output, and distinguish example output from commands. Do not present old output as the result of an updated command.

Software pages and All Package Index content

The All Package Index generates software listings and reusable package includes for sidebars, module lists and installation notes. In handwritten software guides, reuse these includes from referenceinfo/imports/stanage/packages/ rather than copying their content. Do not edit generated metadata includes directly. Custom includes are the exception: their handwritten content is preserved during normal synchronisation. See Software page layout for the normal page layout and All Package Index and generated includes for the generated include files.

Place the generated sidebar above the page title, with the page reference label immediately before the title. Keep installation includes in the installation section. Do not duplicate generated version or product metadata in handwritten prose.

Default examples to the latest version in the generated module list. Verify its executable paths and dependencies. Describe older versions only when a verified difference affects how users load or run the software.

Introduce module-load commands with brief context and reuse the standard interactive-session include where appropriate. Distinguish CPU architecture from node type: software availability for Icelake or Zen 3 is not the same as availability on CPU or GPU nodes.

Job examples

Introduce batch scripts as example batch submission scripts. Explain relevant resource choices and input files; avoid implying that one example suits every workload. Link to the scheduler guidance for general submission instructions.

Use current Slurm commands and variables. Distinguish MPI processes from shared-memory threads, and describe CPU and memory requests consistently with their sbatch directives. For example, --mem requests memory per node, whereas --mem-per-cpu requests it per allocated CPU.

Keep software specific requirements beside the commands they affect. Reuse shared scheduler instructions rather than copying them into each software page.

Validation and test evidence

Run tox -e py313 and inspect the affected rendered pages, including generated includes, links, anchors and formatting. Use a fresh Sphinx environment when checking changes that an incremental build might miss.

Follow executable examples where practical. State what was tested and any untested coverage in the pull request description. Keep detailed logs there or in supporting evidence; add public cautions when findings affect how users run the software.

Scope and maintenance

Keep pull requests focused on the issue being addressed. Avoid unrelated prose rewrites, generated metadata changes or software-version updates.

Update software guidance dates for substantive usage changes as described in Software guidance dates. Reuse shared instructions and keep explanations close to the relevant example so future updates do not leave conflicting copies.