Dokumentation og ansvar

Driftsdokumentation: gør appen uafhængig af hukommelse

En fungerende app er stadig sårbar, hvis kun én person ved, hvor den kører, hvordan den udgives, eller hvad man gør ved fejl. God driftsdokumentation giver en anden person nok overblik til at handle sikkert uden at gætte – også når den oprindelige udvikler ikke er tilgængelig.

Dokumentér beslutninger og handlinger – ikke hver kodelinje

Dokumentationen skal svare på de spørgsmål, som stopper en overdragelse eller gør en driftsfejl farlig: Hvad består løsningen af? Hvem ejer hvad? Hvor findes produktion, data, logs og deployment? Hvilke kontroller skal bestå? Hvordan ruller man tilbage, og hvornår skal man stoppe og eskalere?

README som indgang

Forklar formål, stack, lokal opstart, test, build, hjælp og vedligeholder. Link videre til de længere driftsdokumenter i repositoryet.

Systemkort og afhængigheder

Vis browser eller app, backend, database, filer, login, integrationer, DNS, hosting og de vigtigste dataflow med systemnavne og ejere.

Procedurer og runbooks

Beskriv sikre trin for deployment, rollback, gendannelse, brugeradministration og kendte fejl – med kontrol før og efter handlingen.

Ansvar og kontaktveje

Navngiv en forretningsansvarlig, en teknisk ansvarlig, en stedfortræder og de leverandører, der skal kontaktes ved drifts- eller sikkerhedsproblemer.

GitHub anbefaler, at README-filen forklarer, hvad projektet gør, hvordan man kommer i gang, hvor man får hjælp, og hvem der vedligeholder det. Den er derfor et godt startpunkt, men ikke et sted at presse hele driftsmanualen ind.

Lav et systemkort, som kan kontrolleres mod virkeligheden

Tegn løsningen på én side og forbind hver boks med den konto, det projekt eller den tenant, hvor den faktisk findes. Et enkelt diagram med tekst er bedre end et flot arkitekturbillede uden navne, miljøer og ejerskab.

Brugerflader: Offentlige URL'er, adminflader, mobil- eller PWA-varianter og hvem der bruger dem.
Kørsel: Hosting, backendfunktioner, planlagte jobs, køer og de miljøer, der reelt findes.
Data: Databaser, filområder, søgeindeks, logs og backups – med datatyper og ansvar, ikke følsomt indhold.
Identitet: Loginudbyder, roller, serviceidentiteter og hvor adgang administreres.
Integrationer: Afsender, modtager, autentificeringstype, dataretning og forventet fejl- eller retry-adfærd.
Ejerskab: Hvilken virksomhedskonto betaler, hvem der er administrator, og hvem der kan kontakte leverandøren.

Skriv aldrig secret-værdier i diagrammet. Notér i stedet navnet på secretet, formålet, miljøet, den ansvarlige og den godkendte placering. Dokumentationen skal hjælpe med at finde adgangen – ikke blive en ny kopi af den.

Beskriv en deployment, så den kan gentages sikkert

En procedure skal kunne udføres fra en kendt tilstand og ende med et bevis på, at den lykkedes. Hvis dokumentet blot siger “deploy som normalt”, gemmer det netop den viden, en ny ansvarlig mangler.

Forudsætninger: Krævede roller, værktøjer, branch, godkendelse og hvilke tests eller builds der skal være grønne.
Handling: Den konkrete pipeline eller kommando, forventet miljø og hvordan den udgivne version identificeres.
Datapåvirkning: Migrationer, baggrundsjobs, kompatibilitet og om ændringen kan rulles tilbage uden datatab.
Kontrol: Smoke test, logkontrol, kritisk brugerrejse og den måling, der viser normal drift.
Tilbagevej: Stopkriterier, kendt god version, rollback-trin og hvem der må træffe beslutningen.

Microsoft anbefaler handlingsrettede tjeklister for rutineopgaver og versionsstyrede procedurer med forfatter og gennemgangsdato. Det passer godt til en mappe somdocs/operations/i samme repository som koden, så ændringen kan gennemgås sammen med funktionen.

Skriv runbooks fra symptom til sikker handling

En runbook er en kort procedure til en bestemt driftssituation. Den skal ikke love, at alle fejl har samme årsag. Den skal hjælpe den ansvarlige med at vurdere påvirkning, indsamle bevis, begrænse skade og vælge en afprøvet handling uden at gøre problemet større.

Udløser: Alarm, fejlbesked eller brugerobservation og hvordan den bekræftes.
Påvirkning: Berørte brugere, data og funktioner samt kriterier for alvorlighed.
Bevis: Relevante logs, dashboard, version og seneste ændringer uden at kopiere persondata unødigt.
Sikker handling: Kontrollerede trin, forventet resultat, stopkriterium og tilbagevej.
Eskalering: Navngiven rolle, kontaktkanal, leverandør og hvilken information der skal følge med.
Afslutning: Verifikation, besked til berørte, hændelsesnotat og opfølgende forbedring.

Microsoft og Google fremhæver klare roller, kommunikations- og eskaleringsveje samt løbende opdaterede runbooks som en del af beredskabet. For en lille app kan én side om “appen er nede”, “login fejler” og “data ser forkerte ud” være et realistisk sted at begynde. Indholdet skal passe til de fejl, løsningen faktisk kan få.

Adskil ansvar, adgang og hemmeligheder

En kontaktliste er ikke en adgangsmodel. Dokumentér hvem der ejer forretningen, teknikken og leverandørkontiene, men tildel stadig kun de nødvendige rettigheder og brug virksomhedskontrollerede konti. En navngiven stedfortræder skal kunne overtage uden at dele den primære udviklers private login.

Forretningsansvarlig: Prioriterer bruger- og driftskonsekvens og godkender væsentlige ændringer.
Teknisk ansvarlig: Vedligeholder kode, deployment, overvågning og procedurer.
Stedfortræder: Har afprøvet adgang og kan følge runbooks ved fravær.
Leverandørkontakt: Kender kundenummer, supportkanal og aftale, men dokumenterer ikke adgangskoder i sagen.

GitHubs CODEOWNERS kan knytte personer eller teams til dele af et repository og automatisk bede dem om review, når de relevante filer ændres. Det kan støtte ejerskab i større projekter, men erstatter ikke en bemandingsplan eller dokumenteret driftsadgang.

Test overdragelsen med en person, der ikke byggede appen

Dokumentation er først nyttig, når en anden kan bruge den. Lad en kollega eller leverandør løse en ufarlig, afgrænset opgave uden mundtlige genveje. Den oprindelige udvikler må gerne observere, men bør notere hvert sted, hvor testpersonen må gætte.

Klon projektet og start det lokalt med egne, godkendte testadgange.
Find den aktuelle produktionsversion og den pipeline, der udgav den.
Find logs for en kendt testhændelse uden at få bredere adgang end nødvendigt.
Gennemfør en deployment til et ikke-produktionsmiljø og kontrollér resultatet.
Forklar tilbagevejen og kontaktvejen ved en tænkt driftsfejl.

Gem ikke facit i chatten. Hvis vigtig viden kun findes i en AI-samtale, privat besked eller udviklerens browserhistorik, er den ikke overdraget. Flyt den verificerede del til repositoryets dokumentation eller et godkendt internt system.

Hold dokumentationen levende sammen med appen

En fast kalendergennemgang hjælper, men de vigtigste opdateringer udløses af ændringer: ny integration, nyt miljø, ny datalagring, ændret login, ny ansvarlig, ændret pipeline eller en hændelse, der viste et hul. Læg dokumentændringen i samme pull request, når det er praktisk.

Ejer: Hvert driftsdokument har en navngiven rolle, der må og skal vedligeholde det.
Dato: Vis seneste faglige gennemgang – ikke kun filens seneste formateringsændring.
Bevis: Notér hvornår proceduren sidst blev afprøvet, i hvilket miljø og med hvilket resultat.
Historik: Versionsstyr dokumentationen, så ændringer kan gennemgås og forklares.
AI-assistance: Brug gerne AI til udkast, men kontrollér alle systemnavne, kommandoer, roller og konsekvenser mod kode og cloudkonfiguration.

Typiske fejl

README'en er kun installation: Ingen kan finde produktion, ejerskab, support eller tilbagevej.
Diagrammet viser brands: Der står Azure eller Firebase, men ikke projekt, miljø, dataflow og ansvar.
Secrets kopieres ind: Dokumentet bliver en ny lækagerisiko og er svært at rotere sikkert.
Runbooken er en kommandoliste: Der mangler påvirkning, forudsætninger, forventet resultat og stopkriterium.
Den oprindelige udvikler godkender alene: Ingen uafhængig person har bevist, at vejledningen kan følges.
AI beskriver en tænkt arkitektur: Teksten lyder overbevisende, men matcher ikke de faktiske projekter, rettigheder eller pipelines.
Dokumentet har ingen ejer: Det bliver forældet efter ændringer i system eller team.

Tjekliste før medarbejdere eller kunder bliver afhængige af appen

☐ README forklarer formål, lokal opstart, test, build, hjælp og vedligeholder.
☐ Et aktuelt systemkort viser miljøer, data, integrationer og ejerskab.
☐ Produktions- og leverandørkonti ejes af virksomheden og har en stedfortræder.
☐ Secret-navne og placeringer er dokumenteret uden secret-værdier.
☐ Deploymentproceduren har forudsætninger, kontrol og stopkriterier.
☐ Rollback beskriver både kode, konfiguration og eventuelle dataændringer.
☐ De mest sandsynlige eller alvorlige driftsfejl har korte runbooks.
☐ Kontakt- og eskaleringsveje er tydelige for drift, sikkerhed og leverandører.
☐ Dokumenterne har ejer, gennemgangsdato og dato for seneste afprøvning.
☐ En anden person har startet projektet og fulgt en ufarlig procedure.
☐ Huller fra overdragelsestesten er rettet i den fælles dokumentation.
☐ Ændringer i arkitektur, adgang og drift udløser dokumentationsreview.

Relaterede guides

GitHub til kode, historik og fælles ejerskab Logning og overvågning, som runbooks skal bruge Testmiljø og rollback ved udgivelse Backup og afprøvet gendannelse API-nøgler og secrets uden kopier i dokumentationen Se hele guidebiblioteket

Officielle kilder

Dokumentationens placering, procedurer og ansvar skal passe til appens faktiske stack, risiko og organisation. Kilderne nedenfor beskriver principper og konkrete funktioner; de erstatter ikke kontrol af den valgte cloud-, hosting- og loginløsning.