Veiledning i rapportskriving.

Transkript

1 Veiledning i rapportskriving. v september 1999 Arild Nybraaten INNHOLD 1 SAMMENDRAG INNLEDNING RAPPORTENS INNHOLD - OVERORDNET SYN MÅL MED RAPPORTEN... 3 Overordnet mål OVERORDNET DISPOSISJON ANDRE VIKTIGE FORUTSETNINGER SPRÅKET I RAPPORTEN RAPPORTENS UTSEENDE OPPBYGGING AV RAPPORTEN GENERELT HOVEDELEMENTENE I RAPPORTEN Forside Sammendrag, resultat, vurdering og eventuell konklusjon Resten av rapporten + Vedlegg DETALJERT OPPBYGGING AV RAPPORTEN Forside Innholdsfortegnelse Sammendrag Innledning Teori Utførelse - referat av arbeid Resultater Vurdering - + evt konklusjon Referanseliste Ordliste/forkorteler/begrep Vedlegg OPPSETT AV TEKNISK NOTAT HVORDAN BØR DENNE VEILEGNINGEN BRUKES?... 17

2 1 SAMMENDRAG Retningslinjer for rapportskriving blir gjennomgått ved å sette opp målet for rapporten og å spesifisere oppbygging og innhold for å nå målet. Det brukes en top-down -tilnærming i veiledningen med skrittvis detaljering fra en grov overordnet disposisjon til en gjennomgang av de enkelte kapitler i rapporten Det gis veiledning for to typer rapporter ) En fullstendig teknisk rapport. Dette er en rapporttype som brukes som avslutningsrapporter i mindre og større prosjekter og som milepelsrapporter for større prosjekter med flere faser og store beslutninger ved milepelene 1 ) En forenklet rapport kalt teknisk notat. Denne rapporttypen er beregnet på delrapporter i større prosjekter, eller for små rapporter som senere skal brukes som underlagsrapporter for en større rapport - eller som navnet sier - til et enkelt notat for å orientere om et mindre arbeid. 1 F.ex. om prosjektet skal fortsettes. side 1

3 2 INNLEDNING Dette skrivet er en veiledning for rapportskriving i fagene på "nettlabben" ved HIST-IDB. Ved å følge veiledningen vil det produseres rapporter som best kan karakteriseres som tekniske rapporter. Veiledningen er ikke dekkende for generelle prosjektrapporter eller rapporter for programutviklingsprosjekter. De mest grunnleggende retningslinjene vil allikevel være allmenngyldige for all rapportskriving. Sammen med denne veiledningen hører det to eksempelrapporter en for hver av de to typene som er gjennomgått. Skrivet er en veiledning, ikke en obligatorisk standard. Denne veiledningen har følgende versjonshistorie. Versjon 0.9 skrevet som en tidlig beta høsten 1994 for bruk i klasse 2HSK i faget Nettverksdrift. Veiledningen skrevet som en nødhjelp av faglærer for å avhjelpe manglende opplæring i teknisk rapportskriving. Versjon 0.98 utkastet gjort litt mer ferdig høsten Som eneste veiledning i teknisk rapportskriving ved Institutt for databehandling blir tatt i bruk også i andre fag og av andre lærere. Versjon 1.0 høst 98 fortsatt ingen felles teknisk rapportmal ved instituttet, fortsatt manglende opplæring i teknisk rapportskriving. Versjon 0.98 oppdateres. Fjerning av mye overflødig stoff (og sikkert innsetting av annet overflødig stoff). Endring av layout og skriving av eksempelrapporter. Noe opprydding i det språklige. side 2

4 3 RAPPORTENS INNHOLD - OVERORDNET SYN 3.1 MÅL MED RAPPORTEN OVERORDNET MÅL Målet med en rapport er som navnet sier å rapportere resultatet av et arbeid. Hva betyr det? Det betyr at du skal rapportere til noen. Dette er noe rapportskriveren må ha for øye hele tiden. Du må altså: Definere en målgruppe for rapporten. Sette seg i leserens stilling og skrive slik at leseren på en best mulig måte kan sette seg inn i resultatet av arbeidet. Du skriver altså ikke for deg selv men for noen andre. ) Den du skal rapportere til forutsettes å skulle evaluere arbeidet du har gjort. Normalt er rapporten eneste grunnlag for evalueringen. ) Disposisjonen av rapporten og detaljer/innhold må ha dette som mål. 3.2 OVERORDNET DISPOSISJON Grovdisposisjonen for rapporten er enkel. Hva er gjort - og hvorfor er det gjort. Hvordan er arbeidet gjennomført. Hva er oppnådd. Hva er konklusjonen du trekker på grunnlag av det. Alle disse spørsmålene skal leseren finne svar på ved å ta utgangspunkt i rapporten. I neste trinn skal vi detaljere disposisjonen og dele opp rapporten i kapitler og avsnitt. Da vil vi tilsynelatende fravike denne disposisjonen. Blant annet vil rekkefølgen av kapitlene avvike fra disposisjonen. Dette gjør vi fordi det antas noe om leserens måte å lese rapporten på.. Vi bør heller kalle denne overordnete disposisjonen en logisk disposisjon. Legg merke til at denne logiske disposisjonen er en disposisjon av det avsnittet Sammendrag i rapporten ( se Sammendrag). 3.3 ANDRE VIKTIGE FORUTSETNINGER Det er også en del andre forutsetninger du må gjøre og krav du må følge: Rapporten er leserens eneste inngangsport til arbeidet. Du ikke kan derfor ikke anta at leseren husker fra en visning eller vet at det er gjort selv side 3

5 om det ikke står i rapporten 2. Utgangspunktet må være at det som ikke står i rapporten er ikke gjort. Leseren er travelt opptatt. Det betyr at du må fange interessen i løpet av de første 5 minutters lesing. Leseren skal da vite hva rapporten omhandler og grovt sett resultatet av arbeidet. Hvis leseren fatter interesse og ønsker å se nærmere på arbeidet skal det være lett å finne fram i rapporten. Ut fra rapporten skal leseren kunne finne nok bakgrunnskunnskap og "teori" til å kunne vurdere arbeidet og resultatene. Rapporten må også inneholde forutsetninger og bakgrunn for arbeidet. 3 Rapporten skal om nødvendig inneholde referanser eller henvisninger til mer utdypende teori eller andre kilder. Hvis leseren ønsker det skal han kunne sette seg nærmere inn i bakgrunnen for arbeidet og den underliggende teorien Rapporten skal inneholde de viktigste resultatene som er oppnådd. Disse resultatene skal så vurderes opp mot forventede eller ønskede resultater. Disse forventede eller ønskede resultatene skal angis med begrunnelse. Begrunnelsen kan være teoretisk utledet, komme fra erfaringsdata eller komme fra f.ex en kravspesifikasjon. Avvik eller overensstemmelse mellom forventede og oppnådde resultater skal kommenteres og begrunnes Forsøksbetingelsene skal dokumenteres. I tillegg skal alle resultatene være tilgjengelig, fortrinnsvis som vedlegg eller som tilgjengelige underlagsrapporter. Ut fra dette skal det være mulig å reprodusere arbeidet 3.4 SPRÅKET I RAPPORTEN. Språket i rapporten har mye å si for leserens innstilling overfor en rapport 4. Rapporten skal skrives i et nøytralt fagspråk fritt for muntlige slanguttrykk og unødige forkortelser. Unngå en for muntlig språkføring. Ta hensyn til målgruppen. Det tekniske i språket må tilpasses disse. Alle tekniske uttrykk som målgruppen ikke forutsettes å vite hva er, må forklares. Forklaringen kan være kort, eventuelt med henvisning til referanselitteratur. Legg ved en liste over akronymer 5. Overdriv ikke slike forklaringer. Forutsett en viss minstekunnskap hos målgruppen. Rapporten skal fortrinnsvis skrives i passiv tredjeperson når du refererer hva som er blitt gjort av deg/dere. I teoridel, vurdering av resultater m.v. brukes presensformer. Det gjør et dårlig inntrykk å skifte tid på verbet i ett 2 - eller andre bortforklaringer. 3 Hvorfor arbeidet er gjort, rammebetingelser m.m. 4 - og dermed arbeidet og i siste instans deg som fagperson. 5 Akronymer er tre bokstavers forkortelser ( f.ex. ADSL :-) - som datakommunikasjon og databehandling er så godt forsynt med. side 4

6 og samme avsnitt eller kapittel ( Enda være - i samme setning). "Jeg"- eller vi -formen brukes bare unntaksvis. Skriv fulle setninger. Unngå for mye fyllord og floskler. Kom til saken! RAPPORTENS UTSEENDE Hovedrapporten skal være pent formatert med gjennomført bruk av en dokumentmal. Rapporten skal være paginert og med innholdsfortegnelse. Det er en selvfølge at rapporten skal være godt korrekturlest 7. Lag en mal med nok luft mellom avsnittene. Velg en passe stor skriftstørrelse med et lettlest skriftsnitt. 11pt. er passe i de fleste skriftsnitt, 10 pt. er for lite. Bruk gjerne kapittelnummerering av juridisk type 8. Dette gir bedre oversikt og gjør kryssreferanser lettere. Ikke overdriv den hierarkiske oppdelingen. Sløyf nummerering for kapitler fra nivå 4 eller 5. Ikke bruk for mye pynt i rapporten av typen Clipart eller rammer, selv ikke på forsiden. Vedleggene er bakgrunnsstoff og kan være blandingsformaterte, kanskje håndskrevne notater, utskrifter fra matriseskriver på pysjamaspapir eller for den saks skyld vedlagt på diskett. Vedleggene er beregnet for spesielt interesserte. 6 Denne veiledningen er en versjon *.0 - og er nok ikke så godt språklig gjennomarbeidet som ønskelig. Gjør det bedre dere!-) 7 Sørg for å korrekturlese det som leveres inn. Manglende referanser med som resulterer i Bookmark not defined gir inntrykk av slurv og det inntrykket smitter over på arbeidet. 8 eksempel: Overskrift side 5

7 4 OPPBYGGING AV RAPPORTEN Vi skal så se på oppbyggingen av en rapport del for del. Vi gjør dette i to trinn Vi ser på hvordan leseren antas å bruke rapporten. Med basis i dette settes det opp hvilke kjerneelementer rapporten skal inneholde. Hvert av disse kjerneelementene kan bestå av flere deler. Ved hjelp av innholdsfortegnelse og kryssreferanser skal det være lett for leseren å finne dem. Så går vi gjennom rapporten kapittel for kapittel med kommentarer. Den rapporten som beskrives er en full teknisk rapport. Et Teknisk notat vil ikke inneholde alle disse delene. Det blir satt opp et forslag til hvordan et slikt notat kan settes opp ut fra den fulle veiledningen. 4.1 GENERELT Rapporten bygges opp slik at leseren raskt skal kunne sette seg inn i arbeidet og vurdere resultatene. Vi forutsetter da at rapporten leses i en tretrinns iterativ prosess på følgende måte 9 : 1. Leseren ser på forsiden av rapporten for å finne ut om dette tema eller arbeid er av interesse. 2. Hvis det arbeidet som rapporteres er av interesse, vil leseren ha et sammendrag av arbeidet, hovedresultatet og hovedkonklusjonen. Vurderingen av resultatet er av også interesse. 3. Dersom leseren fortsatt er interessert og ønsker å bruke resultatene til noe, vil han evaluere arbeidet nøyere for å bli trygg på arbeid og resultater. Det gjøres ved å lese rapporten helt eller delvis. Målet er å kunne gå god for arbeid og resultater for å kunne bruke dem i videre arbeid 10. For å føle seg trygg kan det være nødvendig å lese teori eller slå opp i fagbok eller annen referanselitteratur. Hvis leseren ønsker å bruke rapporten som plattform for videre arbeid eller å etterprøve eller verifisere resultatene må alle forsøksbetingelser og alle resultater være tilgjengelige. 4.2 HOVEDELEMENTENE I RAPPORTEN For å kunne tilfredsstille en slik tretrinns lesing av rapporten skal rapporten inneholde følgende kjerneelementer: FORSIDE Forsiden skal inneholde nok opplysninger til å identifisere hvem som har utført arbeidet, hva arbeidet har bestått i, hvor og når arbeidet er gjort. Hvis forsiden ikke gir de riktige opplysningene, vil rapporten raskt bli karakterisert som ikke av interesse. 9 Husk vi har forutsatt at leseren er travelt opptatt og skummer rapporter for å finne den riktige før han starter lesingen for alvår eller for å kunne la arbeidet/prosjektet fortsette eller videreføres. side 6

8 4.2.2 SAMMENDRAG, RESULTAT, VURDERING OG EVENTUELL KONKLUSJON. Neste kjerneelement består av flere deler. Disse skal samlet gi en oversikt over, hva som er gjort, hva resultatet er og en vurdering av resultatet. Disse elementene står ikke samlet i rapporten, men ved hjelp av innholdsfortegnelsen skal det være lett å finne dem. Ved å lese disse vil leseren raskt få tak i det viktigste av arbeidet og resultatet. På grunnlag av dette vil han avgjøre om dette er noe å ofre mer tid på. Regn med at leseren bruker 5 minutter på dette i første omgang. På den tiden skal leseren ha funnet ut om det er verdt å gå videre ned i arbeidet. Dersom leseren må lese videre 11, skal leseren ha fått et godt, positivt og korrekt første bilde av arbeidet på disse 5 minuttene. Sammendrag Rapportens første kapittel med "innhold" er et sammendrag av arbeidet og rapporten. Dette kan være på ca. 1/3-1/2 side. Sammendraget skal være et virkelig sammendrag av hele rapporten, ikke bare informasjon om hva arbeidet har bestått i. Hovedresultat. Hovedresultatene, eventuelt de bearbeidede hovedresultatene skal stå i et eget kapittel seinere i rapporten. Kapittelet må være lett å finne via innholdsfortegnelsen. Dette skal være resultatene, uten noen vurdering. Resultatene kan inneholde opplysninger om måle/forsøksbetingelser hvis det er nødvendig og naturlig. Resultatene skal være i kvantifiserbare (målbare) enheter. Vurdering og eventuell konklusjon. Rapporten skal inneholde en vurdering av resultatene. Vurderingen skal være opp mot de forventede resultatene. Vurderingene skal være med begrunnelse ut fra teori og andre grunnlag for forventningsverdiene. Dersom det er avvik fra forventet verdi skal dette være kommentert med en forklaring på årsaken til dette avviket. Forklaringen for avviket skal ha rot i teori, eller i tall som kan lese ut fra forsøksresultatene (eventuelt rådata). Vurderingen kan gå både på godheten av arbeidet som er gjort, vurdering av resultatet ut fra "teoretisk" forventede resultater, og vurdering av resultatene ut fra en "kravspesifikasjon". Dersom det er naturlig for arbeidet skal det være trukket en konklusjon. Konklusjonen skal være begrunnet, oftest med henvisning til vurderingen av resultatet RESTEN AV RAPPORTEN + VEDLEGG. Resten av rapporten, dvs. innholdsfortegnelse, innledning, teori, planlegging av arbeidet, beskrivelse av arbeidet som er gjort, referanselister, underskrifter 11 f.ex fordi det skal taes en beslutning på grunnlag av nettopp denne rapporten. side 7

9 m.m. utgjør største delen av rapporten. Dette vil være det leseren går gjennom i iterasjon nr 3. Deretter kommer vedlegg av forskjellige typer. Vedleggene vil bare leses dersom leseren ønsker mere dokumentasjon. eller mere bakgrunnsdata. Dersom det er naturlig - eller hvis vedleggsmengden er svært stor, kan vedleggene leveres som separat del. 12 Hva som kan og bør stå i hovedrapporten blir gjennomgått mer systematisk under. 4.3 DETALJERT OPPBYGGING AV RAPPORTEN Vi ser på rapporten - kapittel for kapittel i kronologisk rekkefølge. Hvert kapittel kommenteres med forslag til innhold og utforming. For enkelte rapporter eller typer av rapporter, kan noen av kapitlene utgå eller slås sammen med andre. Forenklede rapporter av type Tekniske notat er gjennomgått i et get kapittel med henvisning til denne gjennomgangen av en fullstendig rapport FORSIDE Forsiden skal inneholde nok opplysninger til å identifisere hvem som har utført arbeidet, hva arbeidet har bestått i, hvor og når arbeidet er gjort. I mange tilfelle vil bedriften ha en standardisert forside som skal fylles ut. Hva som er gjort skal framgå av tittelen på oppgaven. Tittelen på rapporten skal være beskrivende for arbeidet. Tittelen Øving 12 beskriver ikke hva som er gjort. Riktig tittel er f.ex. Installasjon av e- posttjener i lokalnettverk 13 Titler med ordspill hører hjemme i avisoverskrifter - ikke som tittel for en teknisk rapport. Hvem som har utført arbeidet og dato for rapportslutt skal stå på forsida. I tillegg kan forsida inneholde firma- eller institusjonsidentifikasjon. Dette gir tid og sted for arbeidet. Hvis arbeidet er del av et større prosjekt, et fag el.l kan det med fordel framgå av forsida. Forsida inneholder ofte(st) 4-5 stikkord. Dette er stikkord som bibliotekaren ved bedriften legger inn i database for søking. Velg stikkordene med omhu. Regn med at søk kan foretas på enkeltord i tittelen og stikkordene. For ovennevnte tillel kan stikkordene f.ex være Qmail, SMTP, Linux, NT-server og e-post. Brukt sammen med tittelen vil dette gi et ganske presist tilslag i et søk INNHOLDSFORTEGNELSE Rapporten skal ha innholdsfortegnelse. Bruk standard "juridisk/legal" kapittelnummerering. Husk paginering av rapporten. 12 Vedlegget kan være egen rapportdel f.ex. innbundet og mangfoldiggjort, eller som ett tilgjengelig eksemplar i ringperm forutsatt at det er det du har gjort :-) side 8

10 Bruk tekstbehandleren for å generere både kapittelnummereringen og innholdsfortegnelsen. Se over resultatet. Innholdsfortegnelser med feilutskrifter av typen "bookmark missing" tar seg ikke bra ut. Innholdsfortegnelse for vedlegg kan med fordel legges først i vedlegg, eller det kan lages en egen innholdsfortegnelse for dette manuelt. Vedleggene er ofte ikke tekstbehandlet, slik at automatisk generert fortegnelse er vanskelig å få til. I stedet for paginering kan man legge inn fargede skilleark mellom de forskjellige vedleggene, og eventuelt paginere innenfor hvert vedlegg for hånd SAMMENDRAG Sammendraget skal være et fullstendig sammendrag. Du skal ikke bare fortelle hva rapporten omhandler det skal kunne leses ut av en god tittel og av stikkordene på forsiden. Her skal du fortelle noe om innholdet i rapporten, resultater og (eventuelt) vurdering/konklusjon. Hvis rapporten inneholder en teoridel skal også det angis i sammendraget. 14 Disposisjon for dette sammendraget - eller hva sammendraget skal inneholde er likt det som står i kapitlet Overordnet disposisjon. Husk å skrive fulle setninger. Passende størrelse på sammendraget er 1/3 - ½ side INNLEDNING. Innledningen skal gi bakgrunnen for arbeidet som er gjort og bakgrunnen for rapporten. Her kan det komme fram at det er en øving i et fag. Det kan også komme fram at det bygger på... eller at det er en del av en serie øvinger som skal... Her kan du også definere målgruppen for rapporten, og hvilke forutsetninger de må ha. For øvingsrapporter i fag kan målgruppen være definert i oppgaven. Hvis ikke det er gjort, regn med at leseren har et kunnskapsnivå innen faget som er dårligere enn ditt, i hvert fall for det spesielle som rapporten omhandler. Regn f.ex med at leseren står ved starten av det klassetrinnet du er på, eller ikke har det faget du tar. Innledningen skal sette rammen for arbeidet, for rapporten og angi mottakeren av rapporten TEORI. Rapporten må inneholde nok teori til at leseren er i stand til; å forstå bakgrunnen for hva som er gjort forstå hvorfor du har gjort de valgene du har gjort og å bedømme resultatene du har oppnådd 14 f.ex. Grunnleggende teori for Zen og motorsykkelreparasjoner er gjennomgått. side 9

11 Det betyr igjen at når du begrunner dine forventninger, dine konklusjoner og dine vurderinger 15, så skal det finnes teori eller referanser til teorien i dette kapitlet. Du skal selvsagt ikke skrive noen lærebok. Gi oversikt - eller enkel forklaring på teorien her. I tillegg refererer du til litteratur eller andre kilder. Referansene skal gå via referanseliste. Det finnes flere standarder for referanser til referanseliste. Vanlig er å skrive [5] eller Heywood [5] når du henviser til referanse nr. 5 i referanselista. Referanselista kan være plassert som fotnoter etterhvert. Det beste er å ha en egen referanseliste bak i rapporten som eget kapittel. Alternativt kan referansene stå som fotnoter, men dette blir lett uoversiktlig hvis samme referanse brukes flere steder i rapporten. Husk at "teori" ikke betyr "matematikk" eller lignende - men en forklaring på hva og hvorfor. Vær også kritisk med hva du tar med som teori. Det du tar med må være relevant for rapporten og for målgruppen 16. Dette kan f.ex bety: For datakommunikasjon kan det bety prinsippene for kommunikasjonsstakker - og hvordan de et brukt i din maskin. Du forutsetter da at leseren trenger en kort innføring i dette. Hvis du har installert en multiprotokollstakk - f.ex. en NDIS-stakk, så kan du forutsette at leseren kjenner prinsippene for kommunikasjonsstakker generelt 17 og forklare multiprotokollstakker og NDIS spesielt. Forklar også kort hvorfor det er behov for en slik multiprotokollstakk. For skrivere på en Netware-tjener kan det bety at du forklarer prinsippene bak spooling og skriverkøer og "printservere" i Netware. Alternativer er å anta at leseren kjenner prinsippene for spooling men at det er Netware sin måte å gjøre det på som må forklares. Er leseren en ikke-tekniker kan du kort forklare om spooling, skrive et lite avsnitt om at i Netware er dette implementert med spesielle tjenerprogrammer som står mellom skriverkøene og skriverne - kalt Print-servere. Hensvis så til Netwarebok. Hvis du har konfigurert en IP-forbindelse så kan teorien være at du forklare om IP-adresser, routere, subnett og nettmasker. Hvis dette er en rapport i en serie av rapporter, kan du ofte referere til teorien i tidligere rapporter. Du kan ikke sløyfe teorien og bare referere til en lærebok. I rapporten (eller tidligere rapporter) skal det stå nok teori til å gi grunnleggende forklaring. Det er bare hvis leseren ønsker å gå dypere ned i stoffet at læreboka brukes UTFØRELSE - REFERAT AV ARBEID Utførelsesdelen skal beskrive hva du har gjort og hva du har oppnådd. For å kunne vurdere det du har oppnådd og gjort, må du også sette opp planer for 15 og begrunne dem - det skal du 16 Regn med at leseren kan "noe" - ellers blir det lærebok. Du kan f.ex. forutsette grunnleggende kunnskaper i... og så anbefale en lærebok for de som må friske opp bakgrunnskunnskapen ( f.ex. "Stamper [1]") 17 Angi at du forutsetter og henvis evt til en lærebok. side 10

12 arbeidet, og testprosedyrer. Nedenfor er dette satt inn i "underkapitler", men i mange tilfelle vil det være naturlig å fordele stoffet annerledes. Det viktige er at du får fram: Hva planla du å gjøre og hva var målet for arbeidet i målbare verdier. Hva har du gjort Hva var resultatet Hvordan har du sammenholdt forventet og oppnådd resultat. Forutsetninger, betingelser, utstyr Her angir du rammebetingelsene for arbeidet. Eksempler på rammebetingelser er: Programvare. Nett du skal koble deg til. Krav fra "oppdragsgiver". Maskinutstyr m.m. Ett av målene med rapporten er at andre skal kunne reprodusere arbeidet. Det er derfor viktig å angi nøye data som f.ex maskinutrustningen. Sett ikke opp lange spesifikasjonslister i hovedrapporten. Nevn de viktigste data og henvis til detaljer i vedlegg eller manualer og loggmanualer/dokumentasjonsperm. Tilsvarende kan gjelde for de andre forsøksbetingelsene. Planlagt arbeid Du må sette opp hva du skal gjøre for å nå målet. Målet må også beskrives som Planlagte eller forventede resultater. En veiledning for dette er: Planlagt arbeid Beskriv hva du skal gjøre, prinsipielt NB ingen detaljer, bare sett opp hovedtrinnene. Eksempel på en slik beskrivelse kan være: 1. Installere e-posttjener på filtjener 2. Installere klienter på arbeidsstasjonene 3. Teste ut intern og ekstern post 4. Sette opp felles e-postlister og aliaslister for firmaet 5. Utarbeide rutier for vedlikehold av felles postlister og e-postkontoer 6. Skrive bruker- og systemdokumentasjon. Planlagte/Forventede resultater. side 11

13 Hvis du skal kunne bedømme eller vurdere resultatet 18, og se om du har nådd fram til målet så må du angi hvilke resultater du forventer å oppnå. Forventningene må begrunnes i teori eller krav fra oppdragsgiver. Du må angi målet slik at du seinere kan holde resultatet opp mot målet og sammenligne. Målet må være angitt i målbare verdier/enheter. I enkelte tilfelle vil du ikke kunne måle resultatet annet enn ved at det virker. Eksempelet over med installering av et e-postsystem er et slikt tilfelle. Da må du her - eller annetsteds sette opp en plan for utprøving, en sjekkliste eller en slags akseptansetest. Målet skal da angis eksakt ikke bare sjekke at systemet virker. Angi i det ovennevnte tilfelle f.ex. hvilke eksterne adresser og hvilke interne adresser 19 du skal teste. Du kan eventuelt spesifisere dette i avsnittet Testmetoder og testverktøy. Testmetoder og testverktøy. Hvis du skal teste annet enn ved å svare "Ja/Nei", så må du angi hvordan du har tenkt å måle. Begrunnn valget av måleprinsipp. Angi hvilket måleverktøy du skal bruke, gjerne også hvilke egenskaper og begrensninger verktøyet har. Et eksempel kan være at du skal måle hastigheten på et datasamband. Du kan da angi at du vil måle med filoverføring - ftp med en angitt filstørrelse, samt med ping - angitt blokkstørrelse(r). Angi også hvilke tider på dagen du vil måle - hvis hastigheten på sambandet varierer over døgnet. Begrunn gjerne valget av metode. Gjennomført arbeid og oppnådde resultater Beskriv arbeidet med "passe mye detalj". Det er viktig å få fram hva man (prinsipielt) har gjort, og prinsipielt hvordan man har gjort det. Leseren skal ikke kunne rekonstruere arbeidet ditt ut fra dette kapitlet. Hensikten er at det skal gi en god oversikt over arbeidet, hvilke deloppgaver det har bestått av, hvilke vegvalg du har gjort underveis, hvorfor du gjorde disse vegvalgene, hvilke observasjoner du har gjort m.m. Ut fra dette skal leseren kunne bedømme arbeidet, se om du har gjennomført et systematisk arbeid. Hvis arbeidet skal fortsettes skal kapitlet kunne danne grunnlag for nytt arbeid etter andre veger eller i fortsettelsen av den vegen man har gått. Det er viktig å få fram hva man har gjort, ikke i detalj hvordan. 20 Et eksempel kan være: Du skriver at du har lagt til Micro$oft TCP/IP som protokoll. Hvis målgruppen tilsier det kan du angi at det gjøres under Start Æ Innstillinger ÆKontrollpanelÆNettverk og det skal du også gjøre 19 anta f.ex. at du har noen aliaser og noen postlister, en avdelingsorientert adressestruktur, og at eksterne adresser kan være både til Internettadresser og til MHS-adresser altså ikke selve håndgrepene eller tastetrykkene. side 12

14 Du skal ikke angi at du klikker på. add og så på protokoll deretter klikker du på Microsoft i venstre etcetcetc. Det forutsettes at du har ført en loggbok eller en journal med beskrivelse av detaljene. Denne loggboka skal være tilgjengelig som vedlegg dersom man skal reprodusere forsøkene eller vil ha detaljopplysninger. Hvis det er spesielle observasjoner eller uventede/ulogiske ting som leseren bør vite for ikke å falle i samme fellen neste gang, så skal det være referert i rapporten. Eksempel på dette kan være tvetydigheter i manualen eller udokumenterte og vesentlige ting du har oppdaget. Eksempel kan f.ex være hvis man etter installasjon av nettkortdriver fra diskett må slette kortet i oppsettet og la Win95 gjenoppdage det ved PnP. Det kan være vanskelig å finne en passende detaljeringsgrad for dette kapitlet. Vurder bruken av rapporten og målgruppen. Lær deg å føre loggbok og ta vare på loggbøkene 21. Oppnådde resultater Oppgi resultatene du oppnår og observasjoner underveis. Disse kan samles etter hvert hovedtrinn i "utførelse", spredd i teksten, eller flyttes i sin helhet til kapitlet "Resultater". Hvis du får "rådata" som skal bearbeides, f.ex 10 målinger av hastigheten på nettet, eller 100 verdier for kollisjoner i løpet av 100 etterfølgende 2-minutters perioder, så legger du selve rådata i vedlegg og bearbeidede data her. Bearbeiding kan f.ex være kurve eller statistisk behandling RESULTATER Hensikten med dette kapitlet er at leseren skal finne resultatene på ett sted. De resultatene som eventuelt står i utførelsesdelen kan stå innimellom tekst og være fordelt på flere steder i kapitlet. Her skal de derimot stå oversiktlig oppsatt slik at det er lett å få oversikt. Resultatene - gjerne bearbeidet skal gjengis uten kommentarer. Resultatene skal være angitt på kvantiserbar form. For målinger av hastighet, minneforbruk og lignende er dette lett. For kontroll av at ting virker skal det angis nøyaktig hva du har prøvd. Det skal altså ikke stå testet at systemet virket med noen program. Det skal stå hvilke program du har prøvd Eksempel på dette kan være: Word 6.0/95 fra egen harddisk med utskrift av dokument på felles skriver, Excel 6.0/95 fra felles programområde på filtjener, Netscape v. xx (fra egen harddisk) mot http;// og og kopiering av en ca 1Mbyte stor fil til og fra brukerens hjemmekatalog på nettet. 21 Loggboka er beregnet på degselv slik at denne er håndskrevet med forkortelser og personlig stenografi, innlimte utskrifter eller vedlegg med utskrifter fra konfigurasjoner m.m. side 13

15 Resultatene skal være bearbeidet og lett å lese. Dette kan bety tabeller el.l. Dersom det er kjørt flere forsøk 22 og disse er behandlet statistisk, så vil det her stå slike ting som middelverdi, varians o.l. Der det ikke er naturlig med tallresultater, kan tabeller med "avkryssing" og merknader være et alternativ. Vurder selv hvordan du skal "fordele" resultatene mellom "Vedlegg (rådata), resultater og observasjoner knyttet til arbeidsgangen (i "Utførelse") og de "Viktigste" data på bearbeidet form ( i "Resultat"). Når du i neste kapittel skal vurdere resultatene, så er det mot de resultatene du finner i resultat-kapittelet VURDERING - + EVT KONKLUSJON Her skal du vurdere det resultatet - og det arbeidet du har gjort. Vurderingen skjer opp mot hva du forventet og hva som er kravet/ønsket m.m. Som grunnlag for vurderingen legges teori, data/verdier oppgitt i referanser 23. I mange tilfelle kan det også trekkes en konklusjon. Hvis det er naturlig med anbefalinger, eller "råd" for hva man skal gjøre videre, så kommer det her. "Synsing" i vurderingen må underbygges med teori eller målbare data REFERANSELISTE Alle referanser i rapporten skal "peke" på referanser i denne lista. Referansene skal gis på en noenlunde standardisert form slik at målgruppen skal kunne finne dem igjen. Referansene må være til lite "flyktige" plasser. Hjemmeside på WWW er ikke helt trygg, mens f.ex. RFC-er på Internett er greie referanser. Muntlige kilder kan også refereres. I slike tilfelle må den personen som refereres identifiseres godt nok, f.ex. med navn, noenlunde dato og arbeidssted. Eksempler på referanser. Noen rett oppsatte referanser er: Referanse til bok Forfatter(e), trykkeår, tittel, forlegger, eventuelt ant. sider, eventuelt ISBN [1] Comer, D.E, 1991, Internetworking with TCP/IP, Vol 1, 2. ed., Prentice- Hall, 547 pp., ISBN Referanse til tidsskriftartikkel Forfatter(e), trykkeår,, Tittel, tidsskrift m. bind.nr etc, sider 22 Eksempel hastighet ved dataoverføring eller sammenlignende test av nettkort. 23 f.ex. i litteratur, spesifikasjoner, reklameverdier eller tidsskriftartikler side 14

16 [5] Heywood, P., 1995, Compression and Routers, Together at Last, Data Communications Innternational, April 1995, Vol 24, No. 5, Referanse til Manual. Firmanavn, trykkeår (hvis mulig), Tittel på manual, utgivelsessted, kapittel og/eller sidetall andre referansenummer - f.ex. delenummer. [6] Interlan Inc. 1989, NI5210 Installation Manual, Boxborough-USA, s. 2-6 Referanse til rapport Forfatter(e), trykkeår, Rapporttype, Tittel, Institusjon. [12] Ollum, G, 1994, Laboratorierapport i Nettverksdrift, Installasjon av Netware3.11-filtjenner, HIST/IDB-Trondheim Muntlig kilde Identifikasjon av person, Datering, Type meddelelse [13] Einstein, A., Mars 1995, HIST/IDB-Trondheim, Forelesning i relative Databaser. [14] Nymoen, O, Aug. 1995, HIST/IDB-Trondheim, Personlig meddelelse ORDLISTE/FORKORTELER/BEGREP Forkortelser og begrep som du antar at leseren ikke kjenner kan angis her. Vær kritisk - ikke ta med noe "bare for å fylle opp" VEDLEGG Vedlegg av ymse typer, eventuelt med egen innholdsfortegnelse. Dette kan være kopier, håndskrevne ting, rådata etc. etc. side 15

17 5 OPPSETT AV TEKNISK NOTAT. Her må det vel komme noe Foreløpig henvises til eksempler på tekniske rapporter. Hovedprinsippet er det samme som med fulle rapporter Finn målgruppen for notatet Finn hensikten med å skrive et notat beregnet for målgruppen Hvilken informasjon skal du overføre til målgruppen Skriv et notat som gjør at målgruppen får den informasjonen du ønsker å overføre Skriv notatet slik at informasjonsoverføringen blir mest mulig effektiv. Husk at det er bedre å skrive litt for mye enn litt for lite Men hvis det blir alt for mye orker ikke leseren å lese gjennom alt. Det som er viktig å overføre forsvinner derfor lett :-) side 16

18 6 HVORDAN BØR DENNE VEILEGNINGEN BRUKES? Det er en forutsetning at veiledningen oppfattes som det navnet sier - en veiledende rettesnor. Hovedretningslinjene vil i de alle fleste tilfelle danne en grov mal. Detaljutformingen og de enkelte "kapitlene" vil kunne variere fra arbeid til arbeid. Bruk derfor veiledningen med kritisk sans. side 17