Module Documentation Rules

Module Documentation Rules

Module documentation is a user-facing interpretation layer.
It must simplify usage, but never expose internal systems, implementation details, or internal documentation.

::: danger Self-contained & Public-facing
Module documentation must not reference Core, ADRs, RFCs, or any internal documentation.
All information needed to complete a task must exist within Modules.
Cross-references are allowed only within the Modules section.
:::

Use this as the only allowed structure.

**# `<Task Title>`**

**## Overview** — One-line description of what this helps you do.

```md
:::tip At a Glance
**Who is this for?**

<audience>

**When do I use this?**

<trigger / situation>

**What will happen?**

<outcome>
:::

**## Prerequisites** *(if any)* — Required permissions / roles, setup / configuration, dependencies on other modules.

**## Steps** — Sequential, actionable, and minimal. Each step is a `### Step N: <Action>` with a short description.

Screenshot placeholder where a visual would help:

```md
:::info
--------- screenshot here ---------
:::
```

**## Expected Behavior** — What should happen immediately, what may take time (async), what the user will see in UI.

**## Flow** *(optional, recommended for complex features)* — Mermaid diagram. Max 5–6 nodes.

**## Edge Cases / Notes** *(optional)* — Important nuances, non-obvious behavior, limits / constraints.

**## If Something Goes Wrong** *(optional)* — Practical: issue → possible reason → resolution.

**## Related** *(optional)* — Links to other **module docs** only.

Non-Negotiable Rules

0. Complete decoupling

Module docs must never reference:

• Internal implementation details (code, services, hooks, adapters)
• Internal documentation (Core docs, ADRs, RFCs, architecture pages)
• Engineering concepts (state machines, event-driven architecture, normalization layers)

Describe what the user sees and does. Not how the system works.

1. Task-first, not concept-first

Every doc must answer:

"How do I do X?"

❌ Not allowed:

• "Overview of X system"
• "Architecture of X"

Exception: Each module gets one overview.md that lists available tasks with one-line descriptions. It is a navigation page — it must not explain how anything works.

2. No invention of behavior

Modules may simplify, but must never contradict actual system behavior.

If you're unsure how something works, leave it out rather than guessing.

3. No deep system explanation

❌ Not allowed:

• “event-driven architecture”
• “state machine”
• “normalization layer”

✅ Allowed:

• “Processing happens in the background”
• “This may take a few minutes”

4. Screenshots

Use the standard placeholder where a screenshot should be added:

:::info
--------- screenshot here ---------
:::

When real screenshots are added:

• Show only the relevant UI area
• Highlight action points
• Must reflect the latest UI
• Update when the UI changes

5. Diagrams usage rules

• Use only for:

  • async flows
  • multi-system interactions

• Keep simple (max 5–6 nodes)

• No internal implementation details

6. Mandatory sections

These must ALWAYS exist:

• Overview
• Steps
• Expected Behavior

👉 If any missing → doc is incomplete.

"Related" and "If Something Goes Wrong" are included only when relevant. Don't add empty sections.

7. No repetition across docs

If two docs share a concept (e.g., "you must be signed in"), state it once in the relevant doc and link to it from the other. Never duplicate paragraphs across files.

8. Permissions callout

When a task requires a specific role, use a standardized callout:

::: warning Permissions
Requires **Site Admin** role or higher.
:::

Tone Guide

Write like this:

• direct
• actionable
• calm
• user-oriented

Avoid:

• fluffy language
• over-explaining
• engineering jargon

Example tone

✅ Good:

“Click Save to apply changes.”

❌ Bad:

“The system persists the configuration using backend services.”

Future-proofing

As modules grow, you’ll want to extend slightly:

modules/content/
create-content.md
edit-content.md
publish-content.md

👉 Each doc = one task

NOT:

• one giant “content.md”

These rules enforce three things:

1. Uniformity — every doc reads the same way
2. Zero architectural leakage — users never see internals
3. Usability — docs answer real questions, not theoretical ones