Developer Productivity
Set up a team wiki that stays current and actually gets used. Complete guide covering tool selection, structure, ownership, and the habits that keep wikis alive.
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:
## Day 1
- [ ] GitHub access
- [ ] Dev environment setup
- [ ] Slack + team intro
- [ ] Read architecture overview
- [ ] Set up local database
- [ ] Run test suite
- [ ] First PR to shared repo
- [ ] Attend standup
## Week 1
- [ ] Deploy to staging
- [ ] Deploy to production (shadowed)
- [ ] Debug one issue
- [ ] Code review one PR
- [ ] Pair with team member
Owner: Team lead
Review: Every new hire (update based on feedback)
Purpose: Anyone can deploy (reduces bottleneck)
Content:
Example:
## Deployment Checklist
### Prerequisites
- [ ] SSH access to prod
- [ ] AWS credentials configured
- [ ] Latest code merged
### Deploy to Staging
1. `git pull origin main`
2. `npm run build:staging`
3. `./scripts/deploy-staging.sh`
4. Run smoke tests
5. Verify logs
### Deploy to Production
1. Tag release: `git tag v1.2.3`
2. `npm run build:prod`
3. Run full test suite
4. `./scripts/deploy-prod.sh`
5. Monitor metrics
### Rollback (if needed)
1. `git tag v1.2.2` (previous working version)
2. `./scripts/deploy-prod.sh v1.2.2`
3. Verify metrics return to normal
Owner: DevOps/senior engineer
Review: After each deployment (update process if unclear)
Purpose: New people understand system structure
Content:
Example:
## System Architecture
### What We Build
User management platform. Users → Accounts → Permissions
### Components
1. API Service (Node.js)
2. PostgreSQL Database
3. Redis Cache
4. Message Queue (RabbitMQ)
5. Frontend (React)
### Data Flow
1. User logs in → API validates → creates session
2. All requests include session token
3. API validates token against Redis
4. User-specific queries join to permissions
### Why These Choices
- Database: See [ADR-001](./adr-001-postgresql.md)
- Cache: See [ADR-003](./adr-003-redis.md)
- Message Queue: See [ADR-005](./adr-005-rabbitmq.md)
Owner: Architect
Review: Quarterly (or when architecture changes)
Purpose: Handle critical situations without expert
Content: Problem → Solution → Rollback
Example Runbooks:
Example:
## Database Connection Pool Exhausted
### Symptom
"too many connections" error in logs
### Diagnosis
```sql
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)
---
## Tool Selection
### Tool 1: GitHub Wiki (Recommended for Eng Teams)
**Cost:** Free (with repo)
**Pros:**
- Integrated with code repo
- Markdown (version control friendly)
- Can link from README
- No extra tool
**Cons:**
- Limited formatting
- No advanced permissions
- Can't structure deeply
**Best for:** Engineering teams with 5–50 people
### Tool 2: Markdown in Git
**Cost:** Free
**Pros:**
- Full version control
- Can review docs in code review
- Link from code comments
- Searchable
**Cons:**
- Less pretty interface
- Manual navigation
**Best for:** Teams that live in Git/code
### Tool 3: Confluence
**Cost:** $5–25/month per user
**Pros:**
- Enterprise-grade
- Great search
- Permissions
- Team collaboration
**Cons:**
- Can get expensive
- Overkill for small teams
- Steep learning curve
**Best for:** Large organizations (50+ people)
### Tool 4: Notion
**Cost:** $10–200/month
**Pros:**
- Beautiful interface
- Highly flexible
- Good search
- Collaborative
**Cons:**
- Can get slow with large wikis
- Require Notion account for all
- More overhead than simpler tools
**Best for:** Teams that like modern tools
---
## Ownership and Maintenance
### Assign Page Owners
Every page needs an owner.
That person:
- Maintains accuracy
- Reviews changes
- Updates when things change
**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 |
### Monthly Review
First Friday of month: "Wiki Review" (30 min)
Owners review their pages:
- Is it accurate?
- Is it complete?
- Does it need updating?
Update and mark reviewed.
### Link from Code
When code changes, if docs change, link to docs:
```js
// 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.
Build a wiki together. Maintain it together. Benefit from it constantly.
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.