Systemdokumentation som hänger med: vad ska skrivas, och av vem?

Gustav Brochmann

Systemdokumentation som hänger med är kort, ligger nära koden eller arbetet och uppdateras i samband med varje ändring. Fem sorters dokument räcker oftast: översikt, hur man kör och släpper, åtkomst, beslut och användarguide. AI kan hjälpa till att skriva utkast, men en människa granskar.

Dokumentation som ingen läser

Många bolag har antingen ingen dokumentation eller en stor mängd som är inaktuell. Båda lägena är dåliga. Den som tar över, eller den som behöver felsöka en söndag, hittar inte det den behöver. Det bästa målet är litet: skriv det som behövs, och håll det aktuellt.

Fem sorters dokument som räcker långt

  1. Översikt. Vad systemet gör, vilka delar det består av och hur de hänger ihop. Gärna en enkel bild.
  2. Drift och release. Hur systemet körs, hur nya versioner släpps och hur man backar. Se Hur backar man en release som gått fel?.
  3. Åtkomst. Vilka konton och miljöer som finns, vem som äger dem och hur nya personer får tillgång. Skriv aldrig själva lösenorden i dokumentet.
  4. Beslut. Varför något är gjort som det är. En rad om varje större val sparar mycket tid senare.
  5. Användarguide. Hur medarbetarna gör de vanligaste sakerna.

Hur den hålls aktuell

Var AI kan hjälpa

En AI kan läsa kod och ändringshistorik och föreslå ett utkast: en översikt, en beskrivning av en funktion eller en sammanfattning av vad som ändrats. Det sparar tid. Men ett utkast är inte en sanning. En person som känner systemet ska läsa och rätta, eftersom en AI kan beskriva något som ser rimligt ut men inte stämmer.

Frågor till leverantören

  • Var finns dokumentationen, och kan vi läsa den?
  • När uppdaterades den senast?
  • Vem skriver den, och när under arbetet?
  • Skulle en ny person kunna ta över utifrån den?

Det sista är ett bra test. Be någon som inte deltagit läsa översikten och förklara systemet med egna ord.