|
Ref: Mye av underlaget på denne siden er tatt fra "Dokumentasjonsstandard", laget av
Ann-Mari Torvatn, ved Høgskolen i Oslo.
Tekst i denne farge er spesiellt for DmPro prosjekter.
Dokumentasjon
IT gjør tilværelsen både enklere og bedre for utallige mennesker. Datasystemer utfører
oppgaver som man ellers aldri kunne fått utført, eller som det ville tatt uendelig mye tid å
utføre. Datasystemer gir praktiske forbedringer i hverdagen, nytte og glede, ny kunnskap,
innsparinger og god økonomi.
Men datasystemer, spesielt større datasystemer, er oftest ganske komplekse. Det krever
kunnskap og kompetanse å skape dem, og det krever kunnskap og kompetanse å forstå,
vedlikeholde og bruke dem.
Det er ofte stor avstand mellom dem som har designet og implementert et datasystem, og dem
som skal bruke det. Avstanden kan være fysisk, uttrykt i kilometer og mil. Den kan uttrykkes i
tid: et system kan brukes i mange år etter at det er laget. Avstanden kan også ha å gjøre med
kunnskaper og kompetanse. Den som vedlikeholder eller bruker produktet, har alltid mye
mindre kunnskaper om det spesielle systemet enn de som har utviklet det, og ikke så sjelden
har de mindre kunnskaper om data generelt.
Dokumentasjonen skal bygge bru over de avstander som finnes, slik at datasystemet kan
utnyttes fullt ut også av dem som ikke har utviklet det og som står fjernt fra utviklerne – på
den ene eller den andre måten.
Hvilken dokumentasjon som trenges for et dataprodukt, er avhengig av hvem som skal ha
produktet og hva de skal gjøre med det.
For et dataprodukt finnes det vanligvis to typer lesere/brukere.
Den ene gruppen inneholder de personene som er ansvarlige for drift av det aktuelle
produktet, de som skal installere, kjøre, vedlikeholde, modifisere og feilsøke
programsystemet. Disse har bruk for ganske mye informasjon om produktet: om system,
oppbygging, funksjoner, begrensninger, opsjoner, tidligere testing, osv. Denne gruppen vil
normalt være datakyndig på tilnærmet samme nivå som utvikleren.
Den andre hovedgruppen er det vi kaller ”sluttbrukere”: de som skal bruke systemet til det det
er designet for, kanskje til daglig. De trenger informasjon om hvordan produktet kan brukes:
hva det kan brukes til, prinsipper for normal bruk, valgmuligheter, opsjoner. Deres fagfelt er
ofte noe annet enn IT, og de trenger bedre forklaringer for å lykkes med bruken av et ITsystem
enn det driftspersonalet gjør.
Uansett hvem man utvikler programmer for, enten det er for næringslivet eller
utdanningsinstitusjoner, må det lages dokumentasjon for disse to typene brukere. Uten slik
dokumentasjon kan et datasystem i lengden ikke fungere. Kunnskap som bare finnes i hodet
på en bestemt person, utvikleren, er uhyre utsatt og kan bli borte på mange ulike måter.
Det kan være nyttig først å skille mellom to hovedtyper dokumentasjon:
styringsdokumentasjon og sluttdokumentasjon. Styringsdokumentene er dokumenter som
lages under prosessen, og som først og fremst skal støtte den. Styringsdokumentene skal
hjelpe utviklerne til å fullføre prosjektet. Når prosessen er over og prosjektet fullført, har disse
dokumentene gjort sin nytte og har ingen interesse lenger for andre enn eventuelt utviklerne
selv.
Sluttdokumentasjonen er den samlingen av dokumenter som leveres inn til bedømmelse til
slutt, som både beskriver hvilket produkt man skulle lage (kravspesifikasjon), det produktet
som er laget (eventuelt med egen brukerdokumentasjon), prosessen som førte fram til det og
eventuell testing som er utført.
Dette betraktes som styringsdokumenter:
- Prosjektskisse
- Prosjektdagbok
- Forprosjektrapport
- Arbeids- og fremdriftsplan
- Eventuell muntlige eller skriftlig rapportering, f. eks. til veileder
- Kravspesifikasjon*
*Kravspesifikasjonen er både en del av styringsdokumentene og en del av
sluttdokumentasjonen. Den leveres sammen med produktet til slutt for ar sensor og veileder
skal kunne se i hvilken grad denne spesifikasjonen er oppfylt.
Sluttdokumentasjon
Dette betraktes som sluttdokumentasjon, og kan være overskrifter på kapittler i en sluttrapport.
Enkelte ganger kan en eller flere av disse være egnet som et eget dokument. Det er heller ikke alle
prosjekter hvor det er naturlig med alle disse punkter, - og det kan være mer hensiktsmessig
med andre overskrifter. Dere kan se på dette som momenter å vurdere under dokumentasjonen. Rådfør dere
gjerne med veilleder.
I begynnelsen av rapporten kommer også:
I slutten av en rapport kommer også:
- Referanser, som lister opp alle kilder som er brukt i arbeidet. Se
mer info om referanser her.
- Vedlegg, som inneholder nødvendig informasjon for å komplettere rapporten. F.eks kan programlisting
komme her.
Systembeskrivelse
I en del prosjekter vil det være naturlig å beskrive hvordan dagens system er.
Hvordan systemet er før deres prosjekt er gjennomført. Det vil kunne gi et bedre
bilde av bakgrunnen for kravspesifikasjonen, og hvilke forbedringer og/eller innsparinger
man kan forvente med et nytt system.
I forhold til kreative produkter handler det om å ha en dialog med oppdragsgiver (også redaktører, fond osv).
Er det ett rent oppdragsprosjekt er det viktig å finne fram til hvem oppdragsgiver er og hvordan denne vil framstå.
Er det en redaksjon handler det ofte om å finne ut hva denne finner interessant. Hva vil de tenke seg å støtte/vise/formidle?
Studentene må lage lage konkrete forslag til hvilken historie som skal fortelles, på hvilken måte. I mediebransjen
kommer man ikke utenom å lage skisser, piloter og ofte vil man måtte gå flere runder på dette. Dette nærmeste man
kommer en "kravspesifikasjon" vil dermed bestå av en beskrivelse av det som skal lages, (innen film heter det for
eksempel "synopsis", "treatment" og "manus") og ulike skisser, storyboard, prøvepptak, bilder, html "mock ups" osv
Hvis det er en faktaproduksjon er research materialet og resonnementet viktig. I prosjekter der man skal lage interaktive
produkter er målgruppeanalyser, brukerprofiler og lignende vanlig å lage.
Disse objektene former kontrakten mellom dem som skal produsere og dem det skal produseres for.
Kravspesifikasjon
Kravspesifikasjonen er en beskrivelse av de krav som oppdragsgiver/bruker har til det systemet som skal lages,
uttrykt i et symbolsystem som er felles for oppdragsgiver og studenter. Kravspesifikasjonen
må godkjennes av begge parter som den modellen det skal arbeides videre med, og fungerer
derved som en kontrakt mellom partene. Når den er formulert, tjener den som rettesnor for
utviklerne gjennom hele prosjektet.
Viktige data i dette arbeidet er selvfølgelig oppdragsgivers egen beskrivelse av krav og ønsker
til det produktet som skal lages. Kanskje er denne beskrivelsen så klar og utvetydig at
grunnarbeidet er gjort - men den kan også være forholdsvis vag og uspesifisert.
Isåfall må studentgruppen selv spesifisere kravene slik at de blir klare og utvetydige.
Kravspesifikasjonen er en kontrakt med oppdragsgiver om hva som skal
gjøres. Den er altså et meget sentralt del av dokumentasjonen. Den inngår både i forprosjektrapporten og som en del
av sluttrapporten.
Sluttord om kravspesifikasjonen:
En kravspesifikasjon skal ikke være en beskrivelse av det produktet gruppa har laget.
Selv om gruppa etter hvert har fått et klart bilde av hva de skal lage,
skal ikke dette bildets spesielle detaljer komme fram i kravspesifikasjonen. En kravspesifikasjon
skal si hvilken funksjonalitet som kreves - og vanligvis ikke hvordan produktet skal se ut i
detalj. Kravspesifikasjonen kan inneholde et krav om at et skjermbilde skal ha de og de egenskaper -
men det er normalt ikke en del av kravspesifikasjonen akkurat hvordan skjermbildet skal se ut. Kanskje man i
løpet av prosessen er blitt enige med oppdragsgiver om det eksakte utseendet på skjermbildene, men
likevel er ikke dette utseendet en del av kravspesifikasjonen. Kravspesifikasjonen skal være utformet
slik at den ikke peker på et bestemt produkt – den kan tilfredsstilles av mange ulike produkter med ulike
skjermbilder. Gruppas produkt skal være ett av disse produktene.
Teori
Hva er de underliggende teoriene som ligger til grunn for det "empiriske" arbeidet og hvilke problemstillinger søkes
det å finne svar på ved å gjennomføre prosjektet?
Gir prosjektet noe i forhold til den gjeldende teoribasen?
Prosessdokumentasjonen
I prosessdokumentasjonen legger studentene fram bakgrunn og underlag for det produktet
de har laget. De forteller hvilke forhold gruppa har arbeidet under, hvilke arbeidsmåter de har
valgt, hvilke rammebetingelser de hadde, hvilket arbeid som er utført (det er mye som ikke
kommer direkte til syne i produktet), hvilke verktøy som er brukt, hvilke utfordringer arbeidet
har bydd på og hvilke problemer og utfordringer man har funnet gode løsninger på.
Ofte ligger mye av det fortjenstfulle ved arbeidet nettopp i fakta som bare hører hjemme i
prosessdokumentasjonen. Riktig brukt gir prosessdokumentasjonen en god mulighet for
markedsføring for studentene og deres arbeid - uten at det trenger å være formet som skryt.
Av og til skal en gruppe studenter/utviklere fortsette der en annen slapp, eller de skal
implementere en oppgave som er systemert/designet av andre, de skal løse lignende
problemer og/eller bruke samme programvare/utstyr som en tidligere gruppe. De vil kunne ha
stor glede av en skikkelig dokumentasjon av arbeidet, både arbeidsmåten, problemer som er
løst, og utviklingsgangen.
Prosessdokumentasjonen er oftest som en del av sluttrapporten.
I en del tilfelle er det prosessdokumentasjonen som er den egentlige prosjektoppgaven.
Prosjektet er ikke å lage et dataprodukt, men å vise en (ønsket) prosess, beskrive og forklare
et større system eller presentere et resonnement.
Denne biten er mer generell og skriker ikke etter tilpassing. Her er det lett å tenke kreativ prosess med forarbeid,
utprøvninger, omarbeiding, problemer og løsninger. Hvilke valg gjøres og hvorfor? Hvordan forandrer valgene den opprinnelige ideen,
designet, manuset.
Hva sier vi egentlig nå, og hvorfor? Hvordan kan produktet nå forstås, tolkes og brukes, og hvorfor?
Sluttord om prosessdokumentasjonen:
Ulike oppdragsgivere vil som nevnt ha ulikt forhold til prosessdokumentasjonen. Av og til er det nettopp
analysen og prosessen oppdragsgiver ønsker. De resonnementer som ble brukt, de valg som ble gjort,
begrunnelsen for valgene og de følger de fikk - er det viktigste for oppdragsgiver. Kanskje skal
oppdragsgiver bruker prosessrapporten til videre arbeid med et problem. Da er prosessrapporten helt
sentral, og oppdragsgiver vil lete her for å finne det som interesserer mest.
For mange oppdragsgivere vil imidlertid produktdokumentasjonen stå som det vesentligste. Men også
disse vil likevel kunne dra nytte av en solid prosessdokumentasjon. I denne dokumentasjonen samles
fakta om historikk, utvikling, problemer og utprøvde, ikke-fungerende løsninger - alt sammen
informasjon som har klar nytteverdi. Slik informasjon er nyttig når man skal modifisere, feilsøke og
vedlikeholde systemet, og vil kunne utgjøre en erfaringsbank for andre som skal arbeide med lignende
problemstillinger. Sannsynligvis ville mye dobbeltarbeid kunnet unngås hvis man vente seg til å utnytte
allerede dokumentert informasjon.
Produktdokumentasjon
De fleste prosjektoppgaver skal munne ut i et produkt. For eksempel kan det være et softwareprodukt,
et hardwareprodukt, både hardware og software, eller en film.
Man kan også definere en utredningsoppgave som et produkt.
Hvordan produktdokumentasjonen skal utformes, er mye avhengig av hva slags produkt det er snakk om.
Generelt skal dokumentasjonen være så omfattende at ved å lese denne delen vil leseren forstå
produktet, dets oppbygging og virkemåte.
F.eks for et softwareprodukt må man ha all beskrivelse, helt ifra
av hvor dette produkt er plassert i et system til en detaljert beskrivelse av koden. Det er også viktig
å beskrive krav til "omkringliggende" system, f.eks annen software og/eller hardware som dette
produktet skal virke på. Det er viktig å tenke på
at leseren ikke kjenner softwareproduktet fra før. Etter at dokumentasjonen er lest skal leseren
forstå virkemåten så godt at han skal kunne videreutvikle produktet.
Dataansvarlig eller supporter trenger informasjon om installasjon, drift og feilfinning. For å
kunne utføre sine oppgaver trenger den dataansvarlige informasjon om programmets
oppbygging, virkemåte og funksjoner, og om hvilken testing som er gjennomført.
For et hardwareprodukt, som f.eks et kretskort må alle komponenter spesifiseres. Leverandører må angis.
Blokkskjema, kretskjema og printutlegg må være med, i tillegg til en beskrivelse av hvordan det virker.
Ofte vil medieprodukter tale for seg selv. En film er i seg selv en god dokumentasjon på arbeidet.
Når det kommer til interaktive produksjoner er teksten i dokumentet mer relevant.
Nettstedet eller flashapplikasjonen må fungere teknisk og ha noe brukerdokumentasjon, ofte i selve løsningen.
Men som regel er det ikke nødvendig å dokumentere den underliggende softwaren. De fleste webpubliseringsløsninger har
egen dokumentasjon man kan referere til. Hovedfokuset for en dmpro student er å skape gode brukeropplevelser
ved hjelp av eksisterende teknologi og ikke å lage teknologien selv.
Det er dette som er det studentene burde dokumentere / resonnere over her; opplevelsen for tilskueren, brukeren,
deltageren, publikum av det ferdige produktet. Er det en film er det mulig å ha testvisning med spørreskjemaer.
Hvorfor likte de ikke filmen? Hvorfor kom ikke historien vi ville fortelle klart fram? Er det ett interaktivt produkt
kan man gjennomføre "tenke høyt" sesjoner. Ofte kan dette gi en del aha opplevelser. Både at folk oppfatter ting forskjellig,
men også at enkelte ting helt enkelt ikke gir den opplevelsen man trodde. Dette kan munne ut i en "hva vi skulle ha gjort anderledes"
del eller "hva vi har lært".
Ideelt sett burde studentene har gjort slike øvelser også tidlig i prosessen ved hjelp av enkle prototyper,
råklipp og utkast.
Testdokumentasjon
Testdokumentasjonen leveres vanligvis som en selvstendig del av sluttdokumentasjonen. Hvis
det har vært lite testing, kan den utgjøre en del av prosessdokumentasjonen. Den er ellers nært
knyttet til produktdokumentasjonen.
Testdokumentasjonen er viktig for den som skal drifte og vedlikeholde programmet. Solid og
tilstrekkelig testing gjør programmet bedre. Skikkelig dokumentasjon av denne testingen gjør
arbeidet lettere for driftsansvarlig. Det viser sensor og veileder at gruppa satser seriøst på et
hensiktsmessig program og forstår betydningen av testing.
Alle typer testing som er gjort, bør dokumenteres, enten det er det som kalles brukertesting,
eller det dreier seg om feiltesting av programkoden, eller for den saks skyld funksjonstesting.
Det er lurt å legge opp en plan for testingen på forhånd.
Når det gjelder brukerdokumentasjon, er det særlig viktig å ha klart for seg hva man er
interessert i å teste, og hvordan dette kan gjøres. Testplanen må utformes med tanke på disse
to parametrene. Når det gjelder funksjonell testing, må man også bygge opp testplanen etter
slike hensyn, men her kan det ofte bruke et prinsipielt utkast til testplan.
Testplanen bør også bygges opp slik at den med noen endringer (resultater, forklaring av
resultatene og kommentarer til dem) kan bli til testrapport.
Brukerdokumentasjon
Brukerveiledning bør gis både som veiledning på skjermen (prompts, tilbakemeldinger,
statusbeskrivelse, feilhåndtering og hjelpeinformasjon) og ikke minst som skriftlig
brukerveiledning.
I de fleste hovedprosjekter der det finnes et dataprodukt med brukere, er det nødvendig med
skriftlig brukerinformasjon. Når produktet er en webside, må det riktignok være så
selvforklarende at vanlige brukere kan ta det i bruk uten videre. Men ofte er det en
administrator for systemet, som skal kunne endre og redigere den informasjonen som finnes
på nettsiden, og da vil det trenges noe skriftlig brukerinformasjon.
Brukerveiledningen må alltid innrette seg etter de brukerne man regner med – deres behov,
kunnskaper, brukersituasjon, erfaring. Regler for brukerdokumentasjon må derfor alltid
vurderes i forhold til den/de brukere man har å gjøre med.
To typer fakta
Brukerdokumentasjonen på papir beskjeftiger seg i hovedsak med to typer fakta: HVA kan
systemet gjøre – og HVORDAN skal brukeren handle for å oppnå sine mål med systemet?
Disse to typene fakta krever hver sin struktur, og bør ikke blandes alt for tett sammen. I store
systemer plasseres de ofte i hver sin del av en manual eller får til og med to ulike manualer.
Den ene delen, referansedelen, gir en oversikt over systemets muligheter – hvilke systemer,
funksjoner og opsjoner det er mulig å bruke, hvordan de fungerer, og hvordan de hører
sammen. Det er ikke meningen at man skal lese denne delen fra begynnelse til slutt, den er
organisert som et oppslagsverk, og er særlig beregnet på øvede brukere. Man skal her kunne
finne fram til og fordype seg i den funksjonen eller den sammenhengen man har bruk for å
vite mer om.
Den andre delen forteller hvilke prosedyrer som må følges for at man skal oppnå bestemte
mål. Her der det brukerens mål som står i fokus. Denne delen er spesielt nødvendig for nye og
uøvde brukere. Her bør stoffet være organisert som sekvenser av operasjoner som til sammen,
og i angitt rekkefølge, fører til det ønskede resultatet.
Det er flere varianter av prosedural brukerveiledning. Ofte lager man en redusert utgave av
brukerveiledningen med tanke på brukerens situasjon, sånn som miniinnføring eller
referansekort.
Hvis omfanget av systemet ikke er for stort, legge man ofte både referansedel og
veiledningsdel inn i samme manual, og med noen felles kapitler.
Økonomi
Her skal alle kostnadene med å gjennomføre prosjektet komme fram. Det skal være
kostnadene for nødvendig hardware, f.eks. PC, og software, f.eks utviklingsverktøy. Det skal også være med kostandene
ved selve arbeidet. Dette blir jo et fiktivt overslag, da dere studenter ikke får betalt for arbeidet.
Allikevel skal dere skrive hvor mange fakturerbare timer dere har brukt. Sett også en fiktiv pris
per time. Ta også med andre utgifter dere har hatt i forbindelse med å gjennomføre prosjektet, f.eks reise.
Sensor for DmPro prosjektene skriver til slutt:
Det jeg ville forvente å finne i en god sluttrapport er:
- Underliggende oppdatert teori (medier og kommunikasjon) referert på riktig måte med utledete problemstillinger. Teori om brukeropplevelser, kommunikasjon, språk, informasjonsarkitektur, design, estetikk osv vil være viktig.
- Beskrivelse av ulike løsninger og refleksjon rundt disse. Relevant både i forhold til problemstillingene og oppdragsgivers behov. Rikelig med skisser og eksempler som viser at det er ett spenn i idetilfanget.
- Beskrivelse av produksjonsprosessen. Valg (kompromisser) og begrunnelse. Hele tiden relatert til punktene over. Rikelig med eksempler og konkretiseringer.
- Beskrivelse av resultatet. Hvorvidt produktet, arbeidet med det, og mottagelse gir noe i forhold til påstandene/problemstillingene.
|
