dtoro
8175d218c1
- .agents/OIKOS.md: rewrote entire Build Status section from Python 30-day roadmap to Go Phases 1-6 status. Added Python-era backlog preservation. - knowledge/wiki/containers/105-apps.md: added DEPRECATED notices for homelab-mcp and secrets-issuance services, pointing to Go equivalents and cutover checklist. - knowledge/wiki/infrastructure/auto-deploy.md: marked webhook ids 10+11 as deprecated, replaced Go Docker stack. - knowledge/wiki/infrastructure/index.md: noted topology gen as Python with Go DB-native replacement planned. - .agents/operations/hermes-agent.md: updated MCP references from FastMCP SSE Python to Streamable HTTP Go SDK. - .agents/shared/writing-style.md: updated MCP reference, topology note. - .agents/domains/knowledge/schema.md: updated MCP server reference.
76 lines
5.6 KiB
Markdown
76 lines
5.6 KiB
Markdown
# Writing Style
|
||
|
||
Write like a technical reference, not a marketing page. Every sentence conveys new information.
|
||
These rules govern **committed documentation** — wiki pages, READMEs, schemas, skills, `AGENTS.md`,
|
||
plans, investigations, and code comments. They are separate from [caveman.md](caveman.md), which
|
||
governs an agent's *chat responses*; the two do not conflict.
|
||
|
||
New or rewritten pages follow these patterns from day one. Existing pages get updated the next time
|
||
they are touched.
|
||
|
||
## Vocabulary — never use these
|
||
|
||
- Significance puffers: "pivotal", "crucial", "vital", "groundbreaking", "transformative", "testament", "paramount", "invaluable".
|
||
- Analytical verbs: "delve", "leverage", "utilize", "facilitate", "foster", "showcase", "underscore", "streamline", "harness".
|
||
- Poetic nouns: "tapestry", "landscape" (figurative), "realm", "paradigm", "ecosystem" (figurative), "journey" (figurative), "nexus", "cornerstone".
|
||
- Promotional adjectives: "robust", "seamless", "innovative", "cutting-edge", "meticulous", "holistic", "comprehensive".
|
||
- Opening crutches: "In today's world", "In the ever-evolving landscape of", "It's worth noting that", "It is important to note that".
|
||
|
||
Use short, common words: "use" not "utilize", "help" not "facilitate", "show" not "demonstrate".
|
||
|
||
## Voice
|
||
|
||
Describe what systems do and how they work.
|
||
|
||
- **Reference prose** (node pages, cross-cutting infrastructure descriptions, `## Role`, `## Why`,
|
||
`At a glance`) is third-person: state facts about the system, not instructions to a reader.
|
||
- **Recipes, runbooks, and skills** are the exception: second-person imperative is allowed and
|
||
preferred where it makes a procedure clearer ("Edit the Caddyfile, commit + push", "Verify with
|
||
`dig +short`"). This matches how the operator actually works. The vocabulary, structure, and
|
||
cross-reference rules below still apply.
|
||
|
||
## Page shape
|
||
|
||
Every doc-level page follows the same shape so a reader scans it in one pass.
|
||
|
||
1. **One H1 = the page title.** Node pages use `# <id> — \`<name>\``; topic pages use `# <Topic>`.
|
||
2. **Opening definition.** First paragraph, 1–3 sentences, says what the thing is. No motivation, no marketing, no setup.
|
||
3. **Body sections** in the natural order for the topic. Reuse the section templates in [page-templates.md](page-templates.md).
|
||
4. **`## Changelog`** at the bottom of every node/topic page — reverse-chronological, append-only. This section is machine-parsed (Go MCP `get_changelog` in `internal/mcp/server.go`); keep the `### YYYY-MM-DD — title` shape.
|
||
5. **Related links** only at the bottom, only when a reference cannot be woven inline.
|
||
|
||
## Section indexes (folder READMEs)
|
||
|
||
A folder's `README.md` opens with a 1–3 sentence prose intro that says what the section covers, then
|
||
a single navigation table — `| Document | What it covers |` — and nothing else. No stale counts, no
|
||
duplicated prose, no narrative between the intro and the table.
|
||
|
||
## Structure rules
|
||
|
||
- Make every sentence information-dense. Cut filler, qualifiers, and setup phrases. Lead with the concrete fact or action, not why it matters.
|
||
- No participial tack-ons (", highlighting the importance of…"). If the clause adds information, make it a separate sentence.
|
||
- **No meta-commentary about the content itself.** Do not narrate the page's own structure or linking strategy.
|
||
- Prefer **tables** for enumerable items with internal structure (service/port maps, field lists, status grids). Reserve bullets for short non-structured lists.
|
||
- Use the **bold-leading-phrase pattern** for structured points: `**Read-only by construction.** The MCP server never mutates state.` — a bold noun phrase, a period, then the explanation.
|
||
- When enumerating across services or nodes, give each its own `###` sub-section or a table row, not one run-on paragraph.
|
||
- Use backticks for code, paths, hostnames, and file names (`inventory.yaml`, `192.168.8.77`, `pct config`); italics for first-mention terminology.
|
||
- Use `>` blockquotes for caveats and gaps that interrupt the main flow: `> **Outstanding gap.** DNS-vs-inventory drift check not yet wired.` One thought per blockquote.
|
||
|
||
## Diagrams
|
||
|
||
- Mermaid is the default for topology and flow diagrams. `infrastructure/topology.md` is generated by `oikos/gen-topology.py` — do not hand-edit it. (Go DB-native topology generation planned.)
|
||
- ASCII box diagrams are fine for small shape diagrams; keep them to one screen.
|
||
|
||
## Sourcing and cross-references
|
||
|
||
- **Factual discipline.** Every claim is grounded in a cited source, an adjacent linked page, or a directly observable fact (`pct config`, `docker inspect`, running config). Do not write sentences that sound sourced but are inference. When docs disagree with live state, fix the doc and note it in the changelog.
|
||
- **One-sided cross-references.** When two pages relate, the link lives in the page where the connection makes organizational sense. Do not add a back-pointer unless that direction also carries content the reader needs.
|
||
- **Cross-references are content, not catalog.** Inline links arise from the surrounding prose; the linked page must be needed to understand the current sentence. A bottom-of-page "Related" list is the fallback, not the default.
|
||
- Pages link with standard relative markdown links (e.g. a container page links to `../infrastructure/dns.md`), forming a navigable graph. Orphans are a bug.
|
||
|
||
## Code comments and commit/PR prose
|
||
|
||
- Comments explain intent, trade-offs, or constraints the code cannot convey. No diff narration, no type restatement, no section-divider comments.
|
||
- Commit messages and PR descriptions are problem → change → risk → verification, not a file-by-file diff restatement.
|
||
- The banned vocabulary applies the same way in comments and commit messages.
|