Documentation is infrastructure. Done well, it scales the team's knowledge.
Documentation tiers:
1. Strategic / decision-level.
- Architecture Decision Records (ADRs) — significant decisions, rationale.
- Solution Design Documents — per project.
- Roadmap — multi-year direction.
- Investment justifications — why we chose Salesforce, why this stack.
Audience: leadership, future architects.
2. Reference / authoritative.
- Data model documentation — every object, field, relationship.
- Integration map — every flow, source, target, frequency, ownership.
- Sharing model documentation — visualised.
- Security architecture — layered approach.
- Naming conventions and standards.
Audience: anyone working on the platform.
3. Operational / runbooks.
- Common admin tasks — step-by-step.
- Troubleshooting guides — symptom -> likely cause -> fix.
- Disaster recovery — outage response.
- Hypercare runbook — issue triage.
Audience: ops team, on-call.
4. User-facing.
- Quick reference per persona — common tasks.
- Process documentation — how to handle scenarios.
- FAQ — common questions answered.
- In-app guidance — tooltips, walkthroughs in Salesforce.
Audience: end users.
5. Developer / Technical.
- API documentation — Apex / REST endpoints.
- Code style guides.
- Testing patterns.
- Build / deploy guides.
Audience: developers.
Storage:
- Confluence / Notion / SharePoint — readable.
- Git — for code-adjacent docs (ADRs, naming standards).
- In Salesforce — Knowledge articles for user-facing.
- Wiki — searchable, browsable.
Maintenance:
- Owners per page — stale docs are worse than no docs.
- Review cadence — quarterly for stable docs, monthly for fast-changing.
- Sunset old docs — when something is replaced, archive the old.
- Search — readers must be able to find what they need.
Patterns:
- Diagrams over walls of text — visual diagrams stick better.
- Examples — concrete examples beat abstract descriptions.
- Search-friendly — title and headers reflect what readers search for.
- Single source of truth — duplicate docs drift; consolidate.
Common pitfalls:
- Documentation as afterthought — written at end of project; already stale.
- No ownership — everyone's responsibility = no one's responsibility.
- Too long, too detailed — readers don't engage.
- Scattered — Confluence + SharePoint + emails + Slack.
- Never updated — original notes, now misleading.
Senior architect insight: documentation is part of the architecture. Just as you design for performance, design for documentation. Treat it as a deliverable, not an afterthought.
The discipline: every significant decision -> ADR. Every major component -> documentation. Every runbook -> ownership. Without rigor, documentation rots.
A senior architect maintains a documentation map: where does each piece of knowledge live? Who owns it? When was it last reviewed?