Writing Card Documentation

Goal: guide users from “where the model fails → what data the training set lacks → which card to choose → which parameters to set → how to verify improvement,” rather than merely defining parameters in isolation.

Writing style

Core principle: explain like a knowledgeable colleague, not a schema browser

Parameter descriptions are for users, not databases. Repeating one sentence pattern across dozens of cards and hundreds of parameters makes the manual exhausting to read.

Avoid

  • Opening every block with a standalone “Type: X. Default: Y.” line and moving the actual explanation to another paragraph. Type and default are context, not the main point.

  • Using the same template for every parameter: “Sets X,” “Determines whether X,” or “Selects X.”

  • Repeating the same idea in consecutive sentences, such as “sets the displacement distance” followed by “the displacement of each atom.”

  • Never addressing the reader, which makes the page feel like a generated specification instead of practical guidance.

Preferred approach

Compress type and default into one sentence, then move directly to what the reader needs to decide. Vary sentence structure and address the reader naturally when giving advice.

Before (schema-like):

::

After:

::

What changed:

  • The opening is one compact sentence—type, default, and purpose—instead of a standalone metadata line.

  • The reader is addressed naturally, making the explanation sound written for a person.

  • A concrete condition and recommendation replace the vague phrase “consider enabling.”

  • The warning uses direct, human wording instead of generic obligation language.

  • The same meaning is not restated in adjacent sentences.

  • The activation condition is placed at the end so it does not interrupt the main explanation.

Vary sentence structure

Do not always write

Alternative phrasing

Sets X.

X controls… / This value determines… / Changing it affects…

Determines whether X.

When enabled… / When disabled…

Selects X.

Two modes are available… / Choices are… / In most cases, use…

Recommended…

You will usually need only… / In most cases… / Leave this unchanged unless…

When to address the reader

Address the reader when:

  • Giving advice: “You will probably need only the default.”

  • Warning about consequences: “A large value may break bonds; inspect several outputs first.”

  • Explaining a choice: “Choose Exact or Random according to whether the composition must be strict.”

Do not force second-person wording into:

  • Type and enum lists: “str; choices are sphere and cone.”

  • Plain factual statements: “PM is disabled by default because it substantially increases output.”

Required sections

Every card page must contain the following information. Headings may vary, but the content may not be omitted.

#

Question the page must answer

Suggested heading

1

What does this card do?

## What it does

2

Which model failure motivates this card, how is it used, and how is improvement verified?

## Worked example

3

What does each parameter mean, what are its type and default, and how should it be chosen for a real scenario?

## Parameters

4

Copyable JSON presets

## Presets

5

Which cards should be combined, and in what order?

## Recommended combinations

6

How should failures be diagnosed?

## Troubleshooting

7

Which Config_type label is written?

## Output labels

8

What is random, and under which conditions is it reproducible?

## Reproducibility

Separate “when to use / when not to use” and “input prerequisites” sections are optional. Integrate that information into the worked example and parameter guidance instead.

Worked-example template (highest priority)

A worked example must begin with a training-set diagnosis, not merely “set parameters → get output.” Use this structure:

::

Example: Lattice Strain

::

Example: Magnetic Order

### 场景：FM 模型在 AFM 相上预测崩了

bcc Fe 的 NEP 模型，FM 构型推理准确但 AFM 构型能量误差是 FM 的 5 倍。训练集只有一种磁序。

**输入：** bcc Fe 晶体，已知 Fe 磁矩约 2.2 μB
**目标：** 生成 1 FM + 1 AFM + 8 PM，让模型见过不同磁序的局域磁环境
**参数设置：** magmom_map=Fe:2.2, gen_fm+gen_afm+gen_pm, pm_count=8
**输出：** 10 个不同磁序结构
**怎么验证训练集质量改善：** 重训后 FM/AFM 推理能量误差差距应显著缩小

Example: Random Doping

::

Writing parameter sections

Use one consistent structure: every field in the Params dataclass has its own heading, and the key in that heading must exactly match the code.

For a short parameter list with no natural groups, use level-three headings:

::

For many parameters with natural functional groups, use level-three headings for groups and level-four headings for fields:

::

Every parameter block contains:

  • First paragraph: type, default, and the quantity or behavior actually controlled.

  • Second paragraph: physical intuition or a dataset scenario, including a useful scale or decision criterion.

  • Enums: a table listing each real option, its meaning, and when to choose it.

  • Conditional fields: an explicit Effective when: ... line so users know when the field is ignored.

Do not combine several keys under one heading such as Use Seed / Seed (use_seed / seed); split them into ### Use Seed (use_seed) and ### Seed (seed). Do not use placeholder enum tables such as “see the UI dropdown.” List real options—Sobol/Uniform, Collinear/Non-collinear, sphere/cone. Avoid generic text that fits any field. The physical explanation must state how increasing, decreasing, or switching the parameter changes the physical state or data distribution.

Do not include the following in user-facing parameter sections:

  • UI implementation details such as UI Label, field mappings, widget labels, or widget explanations

  • Serialization-internal explanations such as “this is a serialized structure field, not a user option”

  • A separate params parameter block; it is an implementation detail

  • Filler advice such as “start with the default and change it only when you know it affects the distribution”

Common questions

Cover at least these three concrete problem types without generic filler:

  • The card-specific reason output is empty

  • The concrete diagnostic and parameter adjustment for unreasonable output

  • The program’s actual behavior when parameters conflict or exceed bounds

Describe only behavior implemented in code; do not invent automatic recovery.

Recommended combinations

  • Name concrete cards, for example Lattice Strain → Atomic Perturb, instead of placeholders such as “current card → target transformation.”

  • Provide at least two combinations that serve distinct purposes.

Recommended presets

  • Presets must differ materially; do not provide three nearly identical JSON blocks.

  • Add one sentence to every JSON preset explaining the problem it solves and when to choose it.

  • For a simple card, one or two meaningful presets are better than three artificial tiers.

Prohibited content

  • Vague advice such as “start conservative, then scale up.”

  • Template filler such as “run a small sample with defaults first.”

  • A generic physics-caution paragraph unrelated to the card’s actual behavior.

  • Tautologies such as “enable this when you need the enabled behavior; disable it otherwise.”

  • Pseudo-examples with no input, goal, or validation condition.

  • Listing the internal params field as a user parameter.

Maintenance commands

  • python tools/docs/audit_card_docs.py — check field-key consistency and defaults

  • python -m sphinx -W -b html docs/source docs/build/html — build the documentation