Writing Wiki Pages
Wiki vs. README, page titles, freshness, process page structure, and wiki health
Wiki page essentials
- Wiki vs README: wiki = internal team knowledge; README = external project entry point
- Title formula: [Technology] + [specific aspect] + [who/when] — searchable and specific
- Freshness: always include "Last updated" date; mark old pages "Needs review" before deleting
- Process pages: Purpose → process → checklist → SLA → escalation → examples
- One comprehensive page beats three partial ones — prevent sprawl with clear ownership
Question 0 of 5
What is the most important difference between a wiki page and a README?
Wiki = internal team knowledge; README = external project entry point. When to use each:
- README: public-facing, answers "what is this and how do I use it", lives in the repo root
- Wiki page: internal, answers "how do we work", "what was decided and why", "how do I onboard", "what is the on-call process"
- Process: "How we do code review", "Our deployment process"
- Decisions: "Why we chose PostgreSQL over MySQL" (ADR-style)
- Onboarding: "New engineer setup guide"
- Reference: "Service catalogue", "Environment URLs", "On-call runbook"
Which wiki page title is most effective?
Specific technology + what aspect + who it's for is the complete wiki title formula. Why titles matter in wikis:
- Wiki pages are found via search — a specific title is more searchable than a vague one
- Readers decide in 2 seconds whether to open a page based on the title
- A wiki with 200 pages titled "Database", "Frontend", "API" becomes impossible to navigate
- "Redis Cache Eviction Policy — Why We Use LRU and How to Tune It"
- "New Engineer Onboarding — Week 1 Setup Checklist"
- "Incident Response Runbook — Payment Service Outage"
A wiki page has no "Last updated" date and was written 3 years ago. What should you do before using the information?
Verify against source of truth → update or mark as "Needs review". Wiki freshness practices:
- Always include a "Last updated: [date]" line at the top of wiki pages
- Pages older than 6–12 months in fast-moving codebases should be reviewed
- Add a "Needs review" banner rather than deleting — even outdated pages contain historical context
- When you use a wiki page, leave it better than you found it — update what you can verify
Which structure is most appropriate for an internal "How we do code review" wiki page?
Purpose → process → checklist → expectations → escalation → examples. Process wiki page template:
- Purpose (2 sentences): why this process exists and what goal it serves
- What we review: what is in scope (logic, security, tests, naming) vs. out of scope (formatting — that's linting)
- Checklist: concrete items reviewers check
- Response time SLA: "First review within 1 business day; author responds to comments within 4 hours"
- Escalation: what to do if a review is blocked or disagreement persists
- Examples: real examples of constructive vs. unhelpful review comments
What is the biggest risk of having a wiki with too many pages?
Discovery failure + contradiction + trust collapse = wiki rot. The wiki sprawl problem:
- Hard to find: if search returns 20 pages about "deployment", readers give up and ask Slack instead
- Contradictions: three pages with conflicting instructions erode trust in all of them
- Trust collapse: once developers stop trusting the wiki, they stop maintaining it — a self-reinforcing cycle
- Prefer one comprehensive page over three partial ones
- Archive rather than delete — mark as [ARCHIVED] to preserve history
- Add a "See also" section to link related pages and prevent fragmentation
- Assign wiki ownership — who is responsible for which sections