diff --git a/WIKI.md b/WIKI.md index 5e2a106..563a730 100644 --- a/WIKI.md +++ b/WIKI.md @@ -55,7 +55,10 @@ docs/wiki/ - Top-level pages use `NN_name.md` directly. High-volume sections get their own directory, e.g. `03_use_cases/NN_name.md` (nav group "Use Cases"). - **No frontmatter.** Every file opens directly with an H1 `# Title`. -- Navigation labels are derived from the page title, not the filename. +- Navigation labels are short human titles set explicitly in + `docs/mkdocs.wiki.yml` (title case) — often **shorter** than the page H1. + Example: nav label `Basic CRUD` vs page H1 `Use Case 1: Basic FastAPI CRUD API`. + Never use the raw filename slug as the label. - Renumbering: prefixes order pages. When inserting a page, pick the next number in the relevant group (subgroup numbers stay grouped). @@ -64,7 +67,7 @@ docs/wiki/ ## 3. Navigation — `docs/mkdocs.wiki.yml` is the source of truth Every wiki page **must** be wired into the nav defined in -`docs/wiki/../mkdocs.wiki.yml`. If a page is not in the nav, it is orphaned. +`docs/mkdocs.wiki.yml`. If a page is not in the nav, it is orphaned. - The `nav:` block mirrors the directory tree; directories become nested groups. @@ -103,16 +106,20 @@ Every wiki page **must** be wired into the nav defined in - Opens with `# Library Overview`, one sentence about what the library does, then a line stating the page builds the mental model. -- Sections: `## Architecture` (ASCII diagram + numbered layer list), - `## Lifecycle Rules` (table: step / call / why), - `## Which … Should You Use?` (decision table). -- Ends with `## Read Next` (cross-links to the next pages to read). +- Sections: `## 🏗️ Architecture` (ASCII diagram + numbered layer list), + `## 🔄 Lifecycle Rules` (table: step / call / why), + `## 🧭 Which … Should You Use?` (decision table). +- Ends with `## ➡️ Read Next` (cross-links to the next pages to read). ### 4.3 Components page (`02_*`) - Validated reference for the public API surface — describes what each component is for and how the pieces wire together. Keep it usage-level; exact signatures belong in `docs/lib/`. +- Anatomy: numbered sections, one per component (`## 1. MongoConnectionManager`, + `## 2. BaseDocument`, …), with `### 8.1`-style sub-numbering for related + types under a component (e.g. the cache layer's backend / stats / config / + in-memory / redis implementations). Ends with `## Related`. ### 4.4 Use-case page (the most common) @@ -152,8 +159,11 @@ depth-first sections and comparison tables: ### 4.7 Error Handling (`06_*`) / Testing pages -- Scenario-style: explain the failure modes / test approaches, a focused code - block, `## Notes` tip list, `## Related`. +- **Error Handling:** an exceptions table (`Exception | Source | Meaning / fix`), + a `> ` note on which failures are by design, a `## 🚀 FastAPI Mapping Example` + code block, then `## 💡 Tips` bullets, then `## Related`. +- **Testing example (`07_*`):** `## 🚀 Mock-Based Quickstart` (focused code + block), `## 💡 Notes` tip list, `## Related`. Common to all pages: no frontmatter, `---` between every major section, and a `## Related` (or variant) footer as the **last** section. @@ -182,8 +192,8 @@ Examples (from mongo-ops): Variants: -- `## Read Next` — used on the overview page (linear reading order). -- `## Related Resources` — only on `index.md`, one bullet per external resource. +- `## ➡️ Read Next` — used on the overview page (linear reading order). +- `## 🔗 Related Resources` — only on `index.md`, one bullet per external resource. ---