1 Forelesning nr 7 Statisk dokumentasjon TDT4285 Planlegging og drift av IT-systemer Vår 2005 Anders Christensen, IDI

2 Hva er dokumentasjon? 1.Forklaring av systemet? 2.Blueprint for systemet? 3.Infrastruktur for komm. mellom sysadmins? 4.Byråkratisk herk og evig stilskriving? System Dok Implementerer Forklarer

3 Målsetting •Formidle kunnskap mellom sysadmins (kommunikasjon) •Sette et utgangspunkt for systemet (endringshåndtering) •Felles referansepunkt for samarbeid (skalering)

4 Dokumentasjonsfeller •Read-write-forhold. •At alle dokumenterer på hvert sitt vis •Dårlig dok blir ansvarsfraskriving •Å tro at ”dette husker vi, dere...” •Å dokumentere uten en bruksplan •Å skrive dokumentasjonen etterpå.

5 Dimensjoner å måle dok etter •Endringsrate (ggr pr tidsenhet) •Endringsvolum (% pr endring) •Lokalitet (% lokal info) •Spesifiserthet (rutineliste vs oversikt) •Brukshyppighet (daglig vs aldri) •Automatiseringgrad (manuell vs auto) •Omfang (alt vs sporadiske områder)

6 Sammenhenger Fordelaktig •Høy lokalitet •Lavt volum •Lav endringsrate •Indireksjon av hyppige endringer Ufordelaktig •Generaliseringer utover lokal fokus •Manglende struktur •Monotolittisk •Ikke tilpasset lesers kompetansenivå

7 Hva kjennertegner god dok? •Forventninger til format •Forventninger til plassering •Forventninger til fokus •Forventninger til innhold •Forventninger til tilgjengelighet •Forventninger til oppdaterthet

8 Tommelfingerregler for dok •Skap en struktur •Jevnlige reviews og audits •Skap tilgjengelighet •La dok være en del av ”loop’en” •Oppdater! (helst før endring) •Eliminer det som ikke vil bli brukt eller oppdatert.

9 Andre tips... •Visualiser en målgruppe når du skriver •Ha peer review på all dok •Bruk maler og sjablonger •La en disposisjon først

10 Dok-typer: Systemdokumentasjon Format: manualer Innhold: referansedokumentasjon Når: for alle leverte systemer Fare: for mye og for generelt Skriver: leverandør Bruker: alle

11 Dok-typer: Brukerdokumentasjon Format: how-tos, FAQ og guider Innhold: hvordan få ting til Når: for alle tjenester som er levert Fare: rett fokus, nivå og vanskelighetsgrad Skriver: alle Bruker: brukerne

12 Dok-typer Systembeskrivelse Format: tekstlig Innhold: overordnet beskrivelse Når: felles for hele systemet Fare: gjentaking av info fra subdok. Skriver: 3.linje Bruker: alle

13 Dok-typer Systemoversikt Format: diagram, skisser, tabeller Innhold: lokal referanseinformasjon Når: for alle delsystemer Fare: manuell oppdatering Skriver: automatisert av 3.linje Bruker: alle

14 Dok-type : Subsystembeskrivelse Format: tekstdokument Innhold: gjennomgang av alt for et subsys Når: ett dokument for hvert subsys Fare: gjenfortelling av systemdok Skriver: 3.linje Bruker: fortrinnsvis 3. og 2.linje

15 Dok-type: Standard operasjonsrutine Format: trinnvis liste Innhold: fremgangsmåte/prosedyre Når: alle rutineoppgaver Fare: forsøke å håndtere for mange feil Skriver: 3.linje Bruker: 1.linje

16 Dok-type: Test-rutine Format: skrittvis prosedyre med fasit Innhold: testing av funksjonalitet Når: alt som kan slutte å virke Fare: vag fasit eller for omfattende Skriver: 3.linje Bruker: 1.linje og all feilsøking

17 Dok-type: HW-logg Format: historisk dagbok, loggføring Innhold: løpende info om endringer Når: hver gang noe hw-messig skjer Fare: for detaljert nivå Skriver: alle, spesielt 1. og 2.linje Bruker: alle

18 Dok-type: Kommentarer i konfig-filer/prog Format: innbakt som kommentarer Innhold: overordnede forklaringer Når: ved endring av standardverdier Fare: platte selvfølgeligheter Skriver: fortrinnsvis 2. og 3.linje Bruker: alle

19 Dok-type: Hjernemessig ’coredump’ Format: oppramsing i fritt format Innhold: alt som en person kan om noe. Når: ved liten tid Fare: ikke top-down og bredde-først Skriver: hvem-som-helst Bruker: hvem-som-helst

20 Sammenheng mellom dok-typer Systembeskrivelse Systemoversikt Subsystembeskrivelse SOP Testrutiner Systemdokumentasjon HW- logg

21 Rammer for dokumentasjon •En ferdighet som må læres, så sørg for trening for de ansatte. •Skap belønning for å arbeide med systemet og skrive god dok. •Arbeid aktivt med å endre vanene til de som ikke dokumenterer •Lag revisjonsplan for dok

22 Sideeffekter av dokumentering •Lettere å dokumentere et godt enn et stort og kaotisk system. •Vanskeligere å anta – må sjekke •Senker hastigheten i arbeidet :-) •Lettere for flere å arbeide sammen •Muliggjør audit og review

23 Dok er nødvendig for å: •Anonymisere arbeidsoppgaver •Muliggjøre peer review •Spesifisere en normaltilstand •Identifisere forbedringsområder •Angir basis for endringer.