Medan omfattande dokumentation är idealisk, bör omfattningen och formaliteten anpassas efter applikationens kritikalitet, komplexitet och livscykelstadium.
När dokumentation är avgörande
- Affärskritiska system: Driftstopp orsakar intäktsförlust, säkerhetsrisk eller efterlevnadsbrott.
- Reglerade miljöer: SOX, HIPAA, FDA 21 CFR Part 11, GDPR kräver revisionsspår.
- Komplexa integrationer: Flersystemberoenden behöver runbooks för felsökning.
- Hög personalomsättning: Kunskapsbevarande via docs minskar onboarding-risk.
- Katastrofåterställning: Steg-för-steg-återställningsprocedurer är icke-förhandlingsbara.
När lättviktsmetoder räcker
- Legacysystem nära avveckling: Investera i migrationsdokument, inte underhållsdokument.
- Open-source/COTS med leverantörsdokument: Referera till leverantörsdokument; komplettera endast luckor.
- Enkla, lågriskverktyg: README + inline-kommentarer kan räcka.
- Agile/DevOps-sammanhang: Levande dokument (Architecture Decision Records, runbooks i repo) > statiska manualer.
Minimi livskraftiga dokumentationsuppsättning
- Arkitekturöversikt + dataflödesdiagram.
- Distribution/Release-procedur (automatiserad föredras).
- Konfigurationshantering (parametrar, hemligheter hantering).
- Viktiga operativa runbooks: start/stop, backup/restore, skalning, vanliga varningar.
- Incidenthanterings-playbooks för top 5 felscenarier.
- Säkerhetshärdningschecklista.
Styrning
- Tilldela doc-ägarskap; granska kvartalsvis eller post-stor-förändring.
- Versionshantering tillsammans med kod.
- Mått: doc-täckning %, tid-till-lösning med/utan docs.
Rättstorlek dokumentation — nog för att drifta säkert, inte så mycket att den ruttnar.
