Wiki Style Guide

Wiki Style Guide

How this wiki is structured and maintained. The goal: a clean, exhaustive, low-drift knowledge base that stays trustworthy as the code moves.

What belongs here vs. elsewhere

Source	Use it for	Authority
This wiki	Curated, cross-cutting, decision-level context: architecture, ADRs, plans, roadmap, per-subsystem walkthroughs, handbook.	Secondary — mirrors the repo.
Main repository	Code, ADR files, docs/, CONTRIBUTING.md, commitlint.config.cjs, engineering standards.	Canonical. If a page and the repo disagree, the repo wins.
DeepWiki	Auto-generated, ask-anything Q&A over the current code.	Generated — great for code-level lookups, re-indexed from main.

Canonical-source banner

Any page that reproduces or summarizes a file that lives in the repo must open with a banner so readers know where the truth lives and maintainers know what to re-sync:

> **Canonical source:** [`docs/adr/0001-...md`](https://github.com/YosemiteCrew/Yosemite-Crew/blob/main/docs/adr/0001-...md)
> This page mirrors it for browsability; if the two differ, the repo file wins.

Pages that are native to the wiki (roadmap views, indexes, cross-cutting architecture narratives) don't need the banner.

Structure & navigation

• GitHub wikis are a flat page namespace. Hierarchy is expressed through _Sidebar.md (the nav tree shown on every page) and _Footer.md. When you add a page, add it to _Sidebar.md or it becomes an orphan.
• Page file names become URL slugs. Use Title-Case-With-Hyphens.md. No spaces, no &, no ?, no non-ASCII in file names — those produce fragile, percent-encoded URLs.
• One # H1 per page, matching the page title. Use ##/### below it.

Writing conventions

• Map, not manual. For anything that changes with the code (exact commands, config values, file paths), link to the repo rather than pasting a copy that will rot. Reproduce full content only where the plan calls for a self-contained page, and always with the canonical banner.
• Plain hyphens, not em dashes, in all prose (house style; keeps GitHub rendering and copy-paste clean).
• Diagrams in Mermaid — GitHub renders fenced mermaid code blocks natively, so diagrams stay in version control and theme-adapt.
• Link between wiki pages with the slug: [Architecture Overview](Architecture-Overview).
• Prefer tables for indexes (ADRs, plans, roadmap) so they stay scannable.

Keeping it current (anti-drift)

Because several pages mirror repo files, they can drift. To keep drift low:

1. Banner every mirrored page (above) so the canonical file is one click away.
2. When you change a mirrored repo file (an ADR, a plan, engineering standards), update its wiki page in the same change.
3. Quarterly re-sync pass: walk the ADR log, docs/plans/, and the roadmap issues; reconcile status columns; re-index DeepWiki from main.
4. Roadmap pages track GitHub issues by number — update status when an issue closes or an epic advances, rather than duplicating issue bodies.

Editing this wiki

The wiki is a git repository (https://github.com/YosemiteCrew/Yosemite-Crew.wiki.git). Clone it, edit Markdown, commit, and push — or edit in the GitHub web UI. There is no PR flow for wikis, so keep changes tidy and self-reviewed.