Selv om omfattende dokumentasjon er ideelt, bør omfanget og formaliteten stemme overens med applikasjonens kritikalitet, kompleksitet og livssyklusstadium.
Når dokumentasjon er essensiell
- Misjonskritiske systemer: Nedetid forårsaker inntekttap, sikkerhetsrisiko eller overholdelsesbrudd.
- Regulerte miljøer: SOX, HIPAA, FDA 21 CFR Part 11, GDPR krever revisjonsspor.
- Komplekse integrasjoner: Flersystemavhengigheter trenger runbooks for feilsøking.
- Høy omsetning team: Kunnskapsbevaring via docs reduserer onboarding-risiko.
- Katastrofe gjenoppretting: Trinn-for-trinn gjenopprettingsprosedyreer er ikke-forhandelbare.
Når lette tilnærminger strekker til
- Arvesystemer nær pensjonering: Investér i migreringsdokumenter, ikke vedlikeholdsdocs.
- Open-source/COTS med leverandør docs: Referer leverandør docs; suppler bare hull.
- Enkle, lavrisiko verktøy: README + inline kommentarer kan nok.
- Agile/DevOps kontekster: Levende docs (Arkitektur Beslutningsposter, runbooks i repo) > statiske manualer.
Minimums livskraftig dokumentasjonssett
- Arkitektur oversikt + dataflytdiagram.
- Distribusjon/utgivelsesprosedyre (automatisert foretrukket).
- Konfigurasjonsstyring (parametre, hemmelighetshåndtering).
- Nøkkel operative runbooks: start/stopp, backup/gjenoppretting, skalering, vanlige varsler.
- Hendelseshåndtering spillbøker for top 5 feilscenarier.
- Sikkerhetsherding sjekkliste.
Styring
- Tildel doc-eierskap; gjennomgå kvartalsvis eller etter store endringer.
- Versjonskontroll side ved side med kode.
- Mål: doc-dekningsgrad %, tid-til-løsning med/uten docs.
Rettstørrelses dokumentasjon — nok for å operere sikkert, ikke så mye at den råtner.