Documentation Terminology

This page records the naming and wording conventions for user-facing documentation, and the rule for writing the user guide. The goal is to keep the documentation consistent across the user guide, examples, and API landing pages.

Project Names

Use the configured substitutions in prose:

  • Use |pyretis| for the project name.

  • Use |pyvisa| for the visualization and analysis tool.

  • Use pyretis run, pyretis analyse, and pyvisa for command names.

Use the literal package or module name when referring to Python imports, for example pyretis.analysis or pyretis.orderparameter.

Scientific and File Terms

Use these forms in prose:

  • order parameter for the concept.

  • orderparameter only for the input section, package, or module name.

  • Monte Carlo for the method.

  • HDF5 for the format, and .hdf5 or .hdf5.zip for extensions.

  • reStructuredText for the markup language, and .rst for files.

  • Fortran for the language, unless quoting source text that uses another spelling.

Style Notes

Prefer concise, direct instructions. For example, write “Run the analysis with” instead of “The analysis can be executed using”. Keep command examples in literal blocks and wrap filenames, input keys, and command-line flags in double backticks.

When a page describes a workflow, start with the result the user is trying to get, then give the commands or settings needed to get there. If a step depends on a previous example, link to that example near the start of the page.

Writing the User Guide

Comments and docstrings describe the code; the user guide, the example pages and the migration guide tell a user how to operate PyRETIS. The reader wants to know what to set, what the run does with it, and what to do when they want something else. Which function reads a key, or which internal route a value takes, does not help them, even when it is true.

  • A key that a run accepts and ignores is a defect, not a fact to document: the guide promises (Keywords that take no effect on a run) that every key either takes effect or is refused. Refuse it (pyretis.inout.key_table.NO_EFFECT, naming what to set instead) or report it. Never document it as behaviour to rely on, and never say which code reads a key (“read only by create_simulation”). A passage that warns users of such a key, in user terms (on which runs the key does nothing, what to set instead), stays, or is written when the key is reported, until the key takes effect or is refused.

  • Write each statement from the user’s side: the input key with its section ([simulation] allow_setting_change), the command, the file, the result, the message they will see. Do not explain behaviour through the code that implements it (“read by create_simulation only”, “declared in key_table.NO_EFFECT”); name a class, module or function only where the user types, imports, calls or subclasses it (an engine class, an order-parameter class, the functions of the library introduction, python -m pyretis.tools.convert_settings).

  • When a key is refused, or takes effect on some tasks only and is refused on the others, say on which runs, and what to use instead.

  • A keyword table gives each key a description a user can act on, in a few words; the details go into the keyword’s own section.

  • Correct a wrong statement by writing the right one for the user, and keep the explanation that helps them choose (when to restart, when to load). Before replacing a passage, read its earlier versions (its git history) and, for a page PyRETIS 3 had, the PyRETIS 3 page (git show master:<page>): where the older wording was clearer, keep it and correct only what is wrong. Clear any passage that breaks these rules while editing nearby.

  • A test that pins a passage of the guide to the code (a list of keys, a table) keeps the two in step. When the passage is wrong for users, change the passage and have the test re-pinned (tests come from a separate session); never reword the passage around the test.

  • History stays out of the guide, except what a user who brings an input or a run file of an earlier PyRETIS (PyRETIS 3, a legacy-runner input, an output.toml or restart.toml an earlier version wrote) needs: what it does now and what to set instead, and which results or output files differ. It goes into the entry of the key or the page concerned, and into the migration guide.