Developer Productivity
Build async documentation practices for remote teams. How to write documentation that answers questions before they're asked and reduces meeting load.
Your remote team is spread across 4 time zones.
Someone has a question.
They wait 8 hours for synchronous answer.
8 hours lost.
Multiply across team: 40 hours lost per decision.
This is the cost of synchronous culture in async teams.
For remote teams, documentation IS the primary communication medium.
Not meetings.
Not chat.
Written documentation.
When documentation is good:
This guide covers building async documentation practices.
Team spans 4 timezones.
Meeting at 9am East Coast = 6am West Coast.
Someone always loses.
Solution: Write it down.
Everyone reads when it's convenient.
Every question becomes a meeting.
Team is in back-to-back meetings.
No time for focused work.
Meetings become bottleneck.
Solution: Document answers.
People read async.
Meetings become rare.
In meeting: Someone says "we'll do X"
Minutes aren't perfect.
Next week: Different person thought it was Y.
Argument repeats.
Solution: Write decision in document.
Decision is verifiable.
Doesn't change.
In real-time:
One person explains to 10 people.
Takes 10 × 10 min = 100 minutes.
With documentation:
Written once, read 100 times.
Writing = 30 min.
Total time = 130 min for 110 exposures vs. 100 min for 10.
Efficiency increases with scale.
New hire in remote team:
Synchronous: Lots of 1-on-1 meetings to get up to speed
Async: New hire reads docs, learns at own pace
New hire is productive 50% faster.
Documentation is anticipatory.
"What questions will people have?"
"What decisions need to be clear?"
Document those things.
Result: Questions don't need to be asked.
Not just "what" but "why."
Remote workers can't ask for context.
It must be in the document.
Documentation is useless if people can't find it.
No discoverability = docs go unused.
Documentation answers the question someone is trying to solve.
If someone asks: "How do I deploy?"
Document doesn't say: "Deployment is complex"
Document says: "Run: ./scripts/deploy.sh --env prod"
Actionable = solves the problem.
Outdated docs are worse than no docs.
People trust them, they're wrong, decision backfires.
Outdated docs need review schedule.
Mark docs with "Last updated: [DATE]"
Mark docs with "Review by: [DATE]"
When: Major decision made
Content:
Example:
# Memo: Adopt PostgreSQL as Primary Database
**Decision:** Use PostgreSQL (not MongoDB)
**Why:**
- ACID consistency for billing
- Complex queries across tables
- Strong schema for validation
**Alternatives:**
- MongoDB: Rejected because weaker ACID, bad for billing
- DynamoDB: Rejected because AWS lock-in
**Implications:**
- Scaling: Harder than MongoDB
- Schema changes: Require migrations
- Cost: Higher than document stores
**Next steps:**
1. Data modeling (week 1)
2. Migration planning (week 2)
3. Team training (week 3)
Format: Markdown, wiki, Google Doc
Discoverability: Link from README, architecture docs
When: Building new feature/system
Content:
Example:
# Spec: User Permission System
**What:** Grant users fine-grained permissions on resources
**Why:** Support multi-tenant organizations
**Design:**
- Resources: Projects, databases, datasets
- Actions: read, write, admin
- Users have roles with permissions
**Implementation:**
- Database schema for permissions
- Authorization middleware
- Admin UI for setting permissions
**Open questions:**
- Hierarchical permissions? (maybe later)
- Audit trail? (yes, add in phase 2)
Format: Google Doc or wiki
Discoverability: Link from feature roadmap
When: Critical operational procedure
Content:
Example:
# Runbook: Deploy to Production
**Prerequisites:** SSH access, AWS credentials
**Steps:**
1. Tag release: git tag v1.2.3
2. Build: npm run build:prod
3. Deploy: ./scripts/deploy-prod.sh
**Verification:**
- Check: curl https://api.prod/health
- Monitor: Check metrics for 5 min
**Rollback:**
- git tag v1.2.2 (previous version)
- ./scripts/deploy-prod.sh v1.2.2
Format: Wiki or markdown repo
Discoverability: Link from oncall docs
When: Important architecture decision
Content:
Example:
# ADR-001: Use PostgreSQL
**Decision:** PostgreSQL for primary database
**Context:** Need ACID consistency for billing
**Rationale:**
- ACID compliance
- Complex queries
- Strong schema
**Consequences:**
+ Billing guaranteed correct
- Scaling limitations
**Alternatives:** MongoDB (rejected - weak ACID)
Format: Markdown repo or wiki
Discoverability: Link from architecture docs
When: New team member
Content:
Example:
# Onboarding: Engineering
**Day 1:**
- [ ] GitHub access
- [ ] Local dev environment
- [ ] Run tests
- [ ] Read architecture docs
**Week 1:**
- [ ] Deploy to staging
- [ ] Fix first bug
- [ ] Code review training
**Month 1:**
- [ ] Own one feature
- [ ] Deploy to production
- [ ] On-call (shadowed)
Format: Wiki or Google Doc
Discoverability: First thing new hire reads
When: Repeated questions
Content:
Example:
# Engineering FAQ
**Q: How do I deploy?**
A: See [deployment runbook]
**Q: Why PostgreSQL?**
A: See [ADR-001]
**Q: How do I set up local environment?**
A: See [onboarding guide]
Format: Wiki or markdown
Discoverability: Link from README
Don't bury the lead.
First sentence = answer.
Bad: "Deployment is a multi-step process involving building, testing, and uploading to AWS. First, you need to ensure all tests pass..."
Good: "To deploy: Run ./scripts/deploy.sh --env prod"
Remote worker can't ask for context.
Must be in document.
Bad: "Use the blue API"
Good: "Use the staging API (blue) for testing features before production. The production API (green) handles customer traffic."
Every decision links to why (ADR).
Every question links to answer (FAQ).
Every procedure links to runbook.
Result: Reader can drill down as needed.
Headings. Bullets. Bold. Code blocks.
Make it skimmable.
Remote worker scans + finds answer in 1 min.
Bad: Paragraphs of text
Good: Organized with headings and bullets
Every explanation needs example.
"How do I deploy?"
Answer: "Example: Run this command for staging: ./scripts/deploy.sh --env staging"
What's assumed about reader?
Bad: "Set up your dev environment"
Good: "Assumes: Node.js 18+, PostgreSQL 14+, Redis installed"
Cost: Free
Pros:
Cons:
Best for: Engineering teams
Cost: Free (with repo)
Pros:
Cons:
Cost: $10–200/month
Pros:
Cons:
Best for: Non-technical teams also need access
Cost: $5–25/month per user
Pros:
Cons:
Best for: Large organizations
Decisions made in meeting.
Notes aren't complete.
Different people remember differently.
Fix: Write decision memo. Link everywhere.
Document written 6 months ago.
Things changed.
Docs wrong.
Fix: Mark docs with review date. Review before that date.
Doc exists but no one can find it.
Fix: Link from multiple places (README, FAQ, related docs)
"Deployment is complex. Talk to DevOps."
Not helpful.
Fix: Exact steps. Examples. Troubleshooting.
"Set up a webhook"
Example not provided.
Reader stuck.
Fix: Every explanation needs example.
Track: What % of decisions have written records?
Track: How often do people reference docs vs. ask in Slack?
Goal: 3x more docs references than Slack questions
Track: Number of meetings per week
Goal: 50% fewer meetings
Track: How long do decisions take?
Goal: 2x faster
For remote teams, documentation is the primary communication medium.
What to document:
How to write for async:
How to start:
In 3 months:
For team wiki, see Team Wiki Setup Guide. For meeting notes, check Meeting Notes Best Practices.
Document decisions. Answer before asking. Scale forever.
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 an onboarding documentation system that gets new hires productive faster. Templates, structure, and maintenance workflows for effective onboarding docs.
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.