doc-maintenance

Documentation maintenance

中文 · Terms used

Keep NMG documentation useful as an interface between users, Agents, design, and implementation. Use the documentation index to resolve ownership when it is unclear; read its CI contract when changing checks and its bilingual policy when changing paired content.

Before drafting, reorganizing, condensing or publishing reader-facing text, apply the reader-oriented writing and review standard. It owns reader-task structure, controlled-language-inspired expression and semantic acceptance. Structural checks do not replace that review.

Content that can be read locally

Use the writing standard's local-reading criteria for section boundaries, required versus background links, source references and inventory duplication. Its review procedure checks incoming references and the meaning of their targets after a move.

The root bootstrap owns the stable discovery protocol. Changing commands and setup belong at their operational owner; the documentation index resolves which surface owns a fact. This Skill routes that work rather than maintaining another copy of the writing criteria.

Meta-rule: NMG's own rules are governed

Rules and decisions about NMG are themselves NMG artifacts and follow the same discipline as the code they govern. This is the rule that makes every other rule change deliberate rather than silent.

• A rule change is a non-trivial change. Adding, weakening, or moving a standing rule, Skill convention, or decision convention is itself a decision: state what changed, what it replaces or beats (alternatives), and why, in the owning record, in the same change. Never change a rule silently inside a code edit, a commit body, or a prose aside.
• One home per rule. State each rule once at its owner — an AGENTS.md standing order, the owning Skill, or a decision record — and link elsewhere by relative Markdown path. If the same rule appears twice, delete the copy and link the owner.
• Prefer a gate to a reminder. When a rule must be followed in many places or protected against drift, turn it into one mechanical check at its owner rather than restating it. A rule restated everywhere is a rule enforced nowhere.
• Keep a new rule reversible and grounded. Prefer a documented convention over entrenched machinery. A rule that needs new space, or replaces an existing rule, records what it costs and what it beat.
• Most docs need no approval. Approval attaches to normative content that no check can decide, not to the docs/** prefix. The test is if this file were wrong, what would fail? — a check means the check approves, nothing means the edit is free. Where a doc has a checkable property and no check yet, write the check instead of asking. See the approval tiers; a record whose substance the user already agreed goes straight into implemented/ with **Approved:** explicit, and is never parked in proposed/.