Dokumentasjon

Hva, Hvorfor og litt om Hvordan

Basert på materiale fra SAGE og andre kilder

Hva skal du dokumentere

Dokumentere for ditt spesifikke miljø/behov

Kilder som er eksterne er ikke tilgjengelig når du trenger dem.

Hvorfor skal vi dokumentere?

Det er jo ingen som leser dokumentasjonen likevel!

5 Enkle regler for dokuementasjon

Hvem skal lese dokumentasjonen

Kjenn din tema?

Hva er kravene til dokumentasjonen

La det bli en vane!

Annonser!

1. Hvem skal lese denne dokumentasjonen

Vit hvem som leser dokumentasjonen

Hva forventer de av denne dokumentasjonen

Hvordan skal denne benyttes.

Hva er deres ”gevinst” for å lese dette.

2. Kjenn ditt tema

Lite kunnskap gir liten torverdighet.

Sett bort oppgaven til noen som kan det bedre.

NB! Husk punkt 1: hvem skal lese dette?

3. Hva er kravene til denne dokumentasjonen

Hvor mye ressurser skal brukes på å lage denne dokumentasjonen?

Hva skal leseren få ut av den?

Hvordan skal de få tak i den?

Er det begrensninger i hvem som kan se den?

Husk:
Dokumentasjon er sett på som noe en skal kunne stole på!

4. La det bli en vane

All dokumentasjon er levende.

Endringer skjer ofte, vanligvis daglig

En jobb er IKKE ferdig før dokumentasjonen er oppdatert!

Brukerne vil slutte å stole på hva du skriver dersom de finner feil (grove eller viktige)

5 Annonser

Reklamer for det du har laget.

Hvorfor blir ikke dokumentasjonen lest?

Ingen finner dokumentasjonen!

Typer Dokumentasjon (1)

Prosedyrer (steg for steg)

Installasjon av et system eller hardware

Tilpassninger fra annen dokumentasjon

Kan føre til;

Stadardisering av avdelinger og grupper

Grunnlag for automatisering og optimalisering

Grunnlag for Feilsøking

Reduserer tid og krefter andre må bruke på det samme senere.

Kjennetegn:

Under stadige endringer og revisjoner.

Typer Dokumentasjon (2)

Informasjon (hva er gjort og hvorfor)

Nettverkskart

Konfigurasjoner

Programvare oversikt (lisenser og bruksområder)

SLA (Service Level Agreements)

Kjennetegn:

Noe mere statisk innhold. Har en autorativ kilde.

Hvordan skrive god dokumentasjon (1)

Hvorfor dokumenterer jeg dette?

Hvem dokumenterer jeg dette for?

Tips:
Skriv ned svarene i innledningen på dokumentasjonen!

Hvordan skrive god dokumentasjon (2)

God dokumentasjoner er:

Nyttig

Har en hensikt

Dekker et behov

Har akkurat passe med informasjon (ikke for mye eller lite)

Korrekt

Fakta stemmer

komplett

Tilgjengelig

Du finner det når du trenger det!

Hvordan skrive god dokumentasjon (3)

Hva er nok informasjon?

Prosedyre basert dokumentasjon er enkelt:

Når man er ferdig med den oppgaven som skal utføres.

TIPS: Kan dette automatiseres/optimaliseres

Informasjons basert dokumentasjon

Hvorfor dokumenterer du dette?

Se på leserens funksjon og hensikt (oppgave)

Formater og bruksområder (1)

La det bli en vane......

Dokumentasjon er ekstra arbeid!

1 time brukt iløpet av dagen sparer deg kanskje for flere timer om natten....

Tre måter å presentere / tilgjengeliggjøre informasjon.

Papir

WEB

Flate filer (text)

TIPS:

Format påvirker innhold, innhold påvirker format

Formater og bruksområder (2)

PAPIR!

Fordeler:

Fysisk

Kan fraktes

Trenger ingen strøm

Varer lenge ...tja..

Lett å legge til info (korte notater i margen)

Ulemper:

Lett å skade eller ødelegge

Endringer er vansklige å distribuere

Oppbevaring av dokumentasjon .... Tar plass!

Blir fort veldig mye papir.

Formater og bruksområder (3)

Web basert dokumentasjon

Fordeler:

Søkbar

Mye info tar liten plass

Kan velge hva som skal skrives ut

Endringer er distribuert på et øyeblikk

Enkel å sikre (backup)

Kan være strukturert

Ulemper

Søkbar

Ikke nødvendigvis strukturert

Krever mye av leser (utstyr, programvare, strøm....)

Formater og bruksområder (4)

Flat fil (text)

Fordeler:

Søkbar

Mye info tar liten plass

Kan velge hva som skal skrives ut

Lett å sikre (backup)

Ulemper:

Søkbar

Krever mye av leser (utstyr, programvare, strøm..)

Formater og bruksområder (5)

Hva anbefales?

Enkelt svar:

Svar på følgene spørsmål:

Hva skal denne delen av dokumentasjonen brukes til, av hvem og i hvilken situasjon er den ment å hjelpe.

Forslag: En kombinasjon:

Digital presentasjon

Backup kopier både elektronisk og papir (backup + arkiv)

Papir kopi av kritiske deler: katastrofe beredskapsplan e.l

Verktøy for dokumentasjon

Flere alternativer enn det er mulig å liste opp:

OS basert:

Tenk formater og at de færreste har rene og homogene miljøer:

Åpne standarder og formater.

Ikke bruk prpertiære løsninger!

Strategier for dokumentasjon (1)

Vanlige situasjoner eller tilstander

Ingen dokumentasjon, ingen rutiner/regler

Ingen dokumentasjon, men policy finnes

Dokumentasjon og policy finnes

Dokumentasjon finnes, men ingen policy...

Strategier for dokumentasjon (2)

Mest vanlige situasjonen:

Dokumentasjon finnes, men ingen policy...

Det finnes en infrastruktur med alt sitt vesen og utstyr.

Noe dokumentasjon finnes, men den er mangelfull og ukorrekt (gått ut på dato...)

Strategier for dokumentasjon (3)

Viktige punkter:

Hva må vi ha av dokumentasjon

Hva finnes av dokumentasjon

Hva er mest kritisk (viktig)

Etabler rutiner og prosedyrer (policy)

Strategier for dokumentasjon (4)

Elementer i en dokumentasjonspolicy

Begrunnelse for dokumentasjon (forankret)

Oppbevaring og metode for å lage denne.

Hvem er ansvarlig for dokumentasjon

Oppfølging, vedlikehold og kontroll (revisjon)

Krav til formater

Hvilke verktøy skal benyttes

HUSK!

Policy danner rammeverket som skal benyttes.

Strategier for dokumentasjon (4)

Rutine for dokumentasjon: noen punkter

Hvordan og når skal det lages dokumentasjon

Hvordan og hvor skal dette lagres og slettes

Hvordan skal man verifisere at den er korrekt.

Gode kilder til dokumentasjon

SAGE (www.sage.org)
system administrators guild.

Automated Network Discovery Tools:

HP OpenView: http://www.openview.hp.com

IP Sonar: http://www.lumeta.com

Tkined: http://wwwhome.cs.utwente.nl/~schoenw/scotty/

Documentation Policy Examples:

http://www.debian.org/doc/docpolicy

Modular Documentation:

Ament, Kurt. Single Sourcing: Building Modular Documentation. Noyes Publications,2002.

Usability and Design:

Jakob Nielsen: http://useit.com/

Don Norman: http://www.jnd.org/

Dokumentasjon er noe vi tilsynelatene vasser i. Det er readme’s, FAQ, Howto’s eller rett og slett dokumentasjon av det programmet du har kjøpt, lastet ned eller laget selv. (ja, du har vel dokumentert det du har gjort?).

Med sånne mengder dokumentasjon må vi jo ha nok? Eller er dette en falsk trygghet?

Foredraget vil ta for seg litt om typer dokumentasjon, hvordan skrive god dokumentasjon, noen tanker rundt formatet, hva slags verktøy skal / kan man bruke og ikke minst, noen tanker rundt emner som strategi, policy og vedlikehold av dokumentasjon.

Jobber til daglig med arktitektur, sikkehet og design av større publiserings og dokumenthåndterings systemer for bla. Posten.
Håper at mine erfaringer samt noen tips jeg har plukket opp fra bl.a. SAGE og andre kilder vil være til hjelp.

Dokumentasjon

Morten Kjelkenes

2004-01-12T21:53:55