Developer Productivity
Set up a team wiki that stays current and actually gets used.
You want a team wiki.
You want centralized knowledge.
Everyone documented in one place.
You pick a tool (Confluence, Notion, GitHub).
You create structure.
You write docs.
Then...
6 months later, the wiki is a graveyard.
Pages are outdated.
No one reads it.
It's painful to edit.
This pattern repeats everywhere.
Most team wikis fail within 6 months.
Why?
Because tool and structure alone don't matter.
What matters is ownership, maintenance, and integration into work.
This guide covers building a wiki that survives.
"We should document X."
No one is responsible.
Docs get written, then no one maintains them.
6 months later, they're wrong.
People stop reading.
Docs live in multiple places:
No central source of truth.
People don't know where to look.
Wiki is separate from work.
Code reviews don't mention wiki.
Onboarding doesn't include wiki.
PRs don't link to docs.
Result: Wiki is ignored during work.
Someone updates code.
Wiki docs become outdated.
Updating wiki feels like extra work.
It doesn't.
Docs stay wrong.
Wiki has 500 pages.
No hierarchy.
No search.
No navigation.
New person: "Where is deployment docs?"
Can't find it.
Doesn't use wiki.
Team member asks: "How do I deploy?"
Instead of asking someone: They check wiki.
Find answer in 1–2 minutes.
Unblock themselves.
Decision is made: "Why did we choose PostgreSQL?"
Context is documented.
6 months later: New person asks why.
Context is there.
Same question asked 5 times per month.
With wiki: Answer documented once.
After first reading, not asked again.
Senior person unblocked.
New hire arrives.
Day 1: Read core wiki pages.
Can unblock themselves.
Productive immediately.
Pick 5–8 top categories:
Getting Started
How To
Architecture
Operations
Team
Reference
Historical
Purpose: New hire gets productive fast
Content:
Example:
**Owner:** Team lead
**Review:** Every new hire (update based on feedback)
### Priority 2: How to Deploy
**Purpose:** Anyone can deploy (reduces bottleneck)
**Content:**
- Prerequisites (who can deploy?)
- Step-by-step (exact commands)
- Rollback procedure
- Troubleshooting
**Example:**
git pull origin mainnpm run build:staging./scripts/deploy-staging.shgit tag v1.2.3npm run build:prod./scripts/deploy-prod.shgit tag v1.2.2 (previous working version)./scripts/deploy-prod.sh v1.2.2
**Owner:** DevOps/senior engineer
**Review:** After each deployment (update process if unclear)
### Priority 3: Architecture Overview
**Purpose:** New people understand system structure
**Content:**
- Problem being solved
- System components
- Data flow
- Technology choices (with links to ADRs)
**Example:**
User management platform. Users → Accounts → Permissions
**Owner:** Architect
**Review:** Quarterly (or when architecture changes)
### Priority 4: Runbooks
**Purpose:** Handle critical situations without expert
**Content:** Problem → Solution → Rollback
**Example Runbooks:**
- Database backup failed
- API service down
- Memory leak detected
- Deployment failed
- Security incident
**Example:**
"too many connections" error in logs
SELECT count(*) FROM pg_stat_activity;
-- if > 90, we're at limit
SELECT pid, query, query_start
FROM pg_stat_activity
WHERE query_start < now() - interval '5 min';
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE pid != pg_backend_pid()
AND query_start < now() - interval '5 min';
kubectl rollout restart deployment/api
**Owner:** DevOps/SRE
**Review:** After each incident (update if missing step)
### Priority 5: FAQ
**Purpose:** Answer common questions
**Content:** Common questions + answers
**Example:**
Q: How do I get AWS access? A: Slack @ops-team. They add you in 5 min.
Q: How do I deploy to production? A: See How to Deploy
Q: Where's the database schema? A: See Architecture Overview section Database Schema
Q: My local env is broken. What do I do?
A: npm run setup:clean wipes everything and starts fresh
**Owner:** Team lead
**Review:** Weekly (add new questions from Slack)
---
Cost: Free (with repo)
Pros:
Cons:
Best for: Engineering teams with 5–50 people
Cost: Free
Pros:
Cons:
Best for: Teams that live in Git/code
Cost: $5–25/month per user
Pros:
Cons:
Best for: Large organizations (50+ people)
Cost: $10–200/month
Pros:
Cons:
Best for: Teams that like modern tools
Every page needs an owner.
That person:
Ownership list:
| Page | Owner | Last Updated |
| ------------ | ----- | ------------ |
| Onboarding | Alice | 2025-02-10 |
| Deployment | Bob | 2025-02-05 |
| Architecture | Carol | 2025-01-20 |
| Runbooks | David | 2025-02-08 |
| FAQ | Alice | 2025-02-12 |
First Friday of month: "Wiki Review" (30 min)
Owners review their pages:
Update and mark reviewed.
When code changes, if docs change, link to docs:
// See wiki/how-to-deploy.md for deployment steps
async function deploy() {
// ...
}
In important Slack messages, link to wiki:
Q: How do I deploy?
A: See wiki: https://wiki.company.com/how-to-deploy
You document everything.
Result: 500-page wiki, information overload.
Fix: Document only high-impact items (top 30 pages cover 80% of questions).
No search, no hierarchy, hard to find anything.
Fix: Organize logically. Use search. Add table of contents.
"The team maintains this."
Result: No one maintains it.
Fix: Assign specific owner. They're responsible.
Docs exist but are never mentioned during code review, onboarding, or meetings.
Result: People don't know wiki exists.
Fix: Link from README, PRs, Slack, meetings.
Docs were written months ago.
Things changed.
Docs are wrong.
People stopped trusting wiki.
Fix: Monthly review, keep current.
How many people visit wiki per week?
Track: How many questions could be answered by wiki?
New hire productivity ramp:
Savings: 2 weeks per new hire
Team wikis fail without structure, ownership, and maintenance.
To build one that survives:
Start this week:
In 3 months, wiki will be essential to your team.
For documentation culture, see Documentation Culture in Engineering Teams. For onboarding docs, check Onboarding Documentation System.
More WebSnips articles that pair well with this topic.
Build an engineering documentation culture developers will actually use. Covers incentives, templates, tooling, and practices for living documentation.
Build async documentation practices for remote teams. How to write documentation that answers questions before they're asked and reduces meeting load.
Build an onboarding documentation system that gets new hires productive faster. Templates, structure, and maintenance workflows for effective onboarding docs.
Implement Architecture Decision Records to document why you made important technical decisions. ADR template, examples, and workflow for software teams.
Build a personal documentation system for developers. Capture solutions, architecture decisions, and technical context so you never solve the same problem
Manage your developer reading list without backlog paralysis. A triage system for technical articles, papers, and documentation that maximizes learning.