Writing style

Units and quantities

SI unless a field convention makes that perverse, in which case the convention is stated on first use. Every quantity carries its units. Every measurement carries an uncertainty; a mean with no spread is reported as a single observation and labelled as one.

Mathematics

LaTeX, rendered with KaTeX at build time. Inline for symbols in running prose, display for anything a reader might want to refer back to. A result worth referring to gets a named block:

Define every symbol at its first appearance, in the same paragraph. A symbol defined three sections earlier is an undefined symbol.

Derivations are written out rather than quoted. A step that is “obvious” is either written or explicitly flagged as omitted, because the reader who needs it most is the author in two years.

Diagrams

Mermaid source inside the page, never a pasted image. Source can be diffed, reviewed in a pull request and corrected; an exported image will outlive its accuracy and nobody will notice.

Tables

Tables carry units in the header and a consistent precision down each column. A column of numbers at varying precision is a column that has not been checked.

Prose

Write for a competent reader who is not in your head: your examiner, a reviewer, and yourself in two years. Prefer the specific to the general. Prefer the active voice where the actor matters, which in a methodology section is almost always.

State what was done, not what is generally done. “The samples were processed” hides who processed them, when, and with what; that information is the methodology.

Status markers

Every page carries a status. A reader arriving from search must be able to tell a placeholder from finished work in one glance, and in an archive that is mostly placeholders this is not optional.

What not to write

Do not restate a definition that exists elsewhere in the archive; link to it. A second statement of the research question is a second research question, and one of them will fall out of date.