Differences

This shows you the differences between two versions of the page.

--- wiki:style-guide [22/07/2026 00:47] – Create DokuWiki entry style guide bkirk
+++ wiki:style-guide [03/08/2026 23:16] (current) – removed - external edit (Unknown date) 127.0.0.1
@@ Line 1: / Line 1: @@
-====== DokuWiki Style Guide ======
-This guide defines the house style for pages on this wiki. It is intended for human edits and agent compliance passes.
-===== Goals =====
-  * Make pages easy to scan before they are read in detail.
-  * Keep source-backed claims traceable to code, tickets, docs, or prior notes.
-  * Separate verified facts from interpretation and open questions.
-  * Keep page structure predictable so future agents can safely update pages.
-===== Page Types =====
-^ Type ^ Use for ^ Expected shape ^
-| Synthesis | Explaining a subsystem, flow, repo area, or concept | Scope, short version, detailed sections, support notes, sources, open questions |
-| Reference | Jargon, commands, IDs, URLs, paths | Short entries, tables, examples |
-| Report | Time-bound investigation or audit | Context, findings, evidence, recommendations, follow-up |
-| Source note | Raw provenance and source mapping | Links, file paths, excerpts, retrieval notes |
-| Inbox | Unprocessed notes | Brief bullets with enough context to process later |
-===== Page Structure =====
-Use this order for most synthesis pages:
-  - Page title.
-  - One-paragraph purpose statement.
-  - ''Scope''.
-  - ''Short Version'' or ''At a Glance''.
-  - Main body sections.
-  - ''Support Notes'' or ''Operational Notes'', where relevant.
-  - ''Source Files'' or ''Sources''.
-  - ''Remaining Questions''.
-  - ''Related Wiki Pages''.
-For process or flow pages, prefer numbered step headings:
-<code>
-===== API and Domain Flow =====
-==== 1. API Request ====
-==== 2. Guest/Domain Creation ====
-</code>
-===== Headings =====
-  * Use one top-level page title: ''====== Page Title ======''.
-  * Use ''===== Section ====='' for major sections.
-  * Use ''==== Subsection ===='' for numbered flow steps.
-  * Avoid deeper headings unless the page is genuinely large.
-  * Use title case for headings.
-  * Keep headings short and specific.
-===== Writing Style =====
-  * Prefer short, direct sentences.
-  * Start with what the reader needs to know, then add detail.
-  * Keep each bullet focused on one claim or action.
-  * Avoid giant bullets that contain several hidden facts.
-  * Use semicolons sparingly; split long chains into sub-bullets instead.
-  * Use Australian English where spelling differs.
-  * Avoid marketing language, filler, and unexplained confidence.
-===== Source-Backed Claims =====
-When a page is based on code or operational evidence:
-  * Name the source file, class, method, command, ticket, or page.
-  * Include line numbers when they were checked and are useful.
-  * Mark uncertainty explicitly in ''Remaining Questions''.
-  * Do not state inferred behaviour as fact unless the source confirms it.
-  * If the source may drift, phrase line numbers as checked evidence rather than permanent anchors.
-Good:
-<code>
-''CreateGuestCommandHandler.Handle()'' was checked at line 64 during this pass.
-</code>
-Avoid:
-<code>
-This always happens here forever.
-</code>
-===== Lists =====
-Use bullets for unordered facts and numbered lists for ordered flows.
-Good:
-<code>
-  * Validates the customer and request.
-  * Builds the guest creation parameters.
-  * Queues the host command.
-</code>
-For call explanations, use the call as the parent item and details as sub-points:
-<code>
-  * ''GuestPlanApiService.CreateServer()''
-    * Loads the customer.
-    * Validates the request.
-    * Queues the create command.
-</code>
-Avoid mixing unrelated ideas in one bullet.
-===== Code, Paths, and Identifiers =====
-  * Use DokuWiki inline code markup for identifiers: ''GuestStatus.Active''.
-  * Use ''<code>...</code>'' blocks for commands, snippets, and trees.
-  * Use bold labels for metadata fields such as **Source:** and **Entry point:**.
-  * Use paths exactly as they appear in the repo.
-  * Do not wrap normal prose in code formatting.
-  * Prefer source paths over vague references such as "the service" when the page is source-backed.
-===== Tables =====
-Use tables for compact comparisons, state transitions, matrices, and indexes.
-  * Keep table cells short.
-  * Do not put long paragraphs in table cells.
-  * If a table needs multiple sentences per cell, use a list instead.
-===== Links =====
-  * Link related wiki pages in ''Related Wiki Pages''.
-  * Use stable internal links where possible: ''[[syntheses:compute-host-stack|Compute Host Stack]]''.
-  * Use external links only when the external source is part of the evidence.
-  * Do not rely on bare URLs when a named link would be clearer.
-===== Process Pages =====
-For workflow and provisioning pages, use this pattern per step:
-  * **Source:** file or component being described.
-  * **Entry point:** method, command, job, or handler.
-  * **What it does:** short action bullets.
-  * **Result:** state change, queued work, or observable effect.
-  * **Failure behaviour:** only if relevant to that step.
-Keep failure paths close to the step they affect, then summarise them again in a dedicated failure section if the page needs a support view.
-===== Support Notes =====
-Support-facing sections should answer practical questions:
-  * What customer-visible symptom appears?
-  * Which internal state is likely involved?
-  * Which command, log, queue, or source area should be checked first?
-  * What should not be promised to the customer?
-Do not turn support notes into a full runbook unless the page is meant to be a runbook.
-===== Open Questions =====
-Use ''Remaining Questions'' for anything unresolved.
-Good open questions are specific:
-  * Which scheduled job terminates suspended failed-create guests?
-  * Which customer-facing label maps to ''GuestStatus.Active'' in the current panel?
-Avoid vague placeholders:
-  * Investigate more.
-  * Check everything.
-===== Compliance Checklist =====
-Use this checklist when reviewing a page:
-  * The title and first paragraph say what the page is for.
-  * Scope is explicit.
-  * Claims are source-backed or clearly marked as open questions.
-  * Long bullets are split into parent/sub-bullets.
-  * Ordered flows use numbered lists or numbered headings.
-  * Code identifiers use DokuWiki inline code markup.
-  * Metadata labels use bold text, not inline code.
-  * Tables are used only where they improve scanning.
-  * Related pages are linked.
-  * No raw credentials or secret values appear on the page.
-  * The page has no accidental heading joins or malformed DokuWiki syntax.
-===== Agent Editing Rules =====
-Agents updating this wiki should:
-  * Fetch the current raw page before editing.
-  * Preserve human-written meaning unless explicitly asked to rewrite it.
-  * Save through the normal DokuWiki edit form, not a blind endpoint.
-  * Verify the raw page after saving.
-  * Record any new durable access or workflow lesson in workspace memory, without storing secrets in plaintext.