Førstehjælp til Rapportskrivning

Førstehjælp til Rapportskrivning Rune Andresen og Jon Sporring 4. januar 2005 1 Forord Dette dokument er skrevet for at hjælpe studerende med at skrive rapporter på Datalogisk Institut og specielt med henblik på G-opgaven på Maskinarkitektur. Det er på ingen måde en facitliste, og at følge den slavisk giver dermed heller ikke en garanti for at bestå! 2 Gode råd til rapportskrivning Det primære mål med at skrive en rapport er at kommunikere en løsning af en given opgave, hvor opgaven typisk er defineret af den studerende eller af undervisere. Rapporten vil som regel blive lagt til grund for en bedømmelse, og sommetider vil den danne grundlag for videre arbejde udført af andre studerende. I begge tilfælde er det vigtigt, at rapporten afspejler den proces, som de studerende har gennemgået for at nå til en given løsning (eller mangel på samme). Det er ofte en god ide, at forestille sig, at adressaten er en medstuderende på samme niveau som forfatterne, men som ikke har forsøgt sig med en løsning af pågældende opgave. Beskrivelsen af processen vil typisk ikke være kronologisk, da en given løsning ofte er nået af omveje. For læsevenlighedens skyld er det en god ide at opbygge en rapport logisk. I skriveprocessen er det derimod som oftest en god ide at føre noter kronologisk, som man senere kan bruge som udgangspunkt til rapportskrivningen. Det er vigtigt at tænke på, at en rapport er et produkt i sig selv. Hvis den ikke er gennemarbejdet, vil det lede til irritation hos læseren, som evt. vil affærdige den som dårligt arbejde på trods af et muligt solidt grundlag. Endeligt er det vigtigt at indse, at vi alle har forskellig måder at skrive på. Nedenfor er der givet en kort liste over ting, der er vigtige at huske: En rapport skal bygges op logisk En rapport er ikke en dagbog. Besvarelsen bør være en fremadskridende forklaring på den løsning man er kommet frem til. Det er nyttigt at have for øje, hvad der er den røde tråd igennem hele rapporten, når man skriver. 1

Vær konsistente i jeres skrivestil Det er ofte god skrivestil at skrive i passiv form, undtagen når I træffer valg. Derudover kan alle problemer, I tager stilling til i jeres opgave, med fordel have følgende overordnede struktur: Problembeskrivelse, løsningsmuligheder, fordele og ulemper ved de forskellige løsninger og endeligt jeres valg. Selvom denne opdeling er lidt mekanisk, så vil læseren hurtigt vænne sig til stilen, og derfor hurtigt lære at læse hurtigt henover dele, læseren finder uinteressant. En rapport skal kunne læses på mange måder Nogle læser først introduktion og konklusion før de beslutter sig for at læse detaljerne. Andre bladrer rapporten igennem for kun at kigge på figurer og figurtekster. Nogle læser slavisk fra start til slut. Så husk at gøre rapporten anvendelig på mange måder. Hvis I har en bestemt læsestil i tankerne, når I skriver, kan det være en god ide at skrive dette eksplicit i forordet. Et billede siger mere end tusind ord Det kan ofte betale sig, at lave en figur frem for at meget indviklet forklaring. Men husk at lave en god figurbeskrivelse, hvor alle de væsentlige dele er beskrevet, såsom aksenavngivning osv. Vigtigt er det, at figurer og tekst skal komplementere hinanden. Lær at mestre begrænsningens svære kunst At vælge hvad der skal med og ikke med i en rapport er noget af det sværeste overhovedet ved at skrive. På den ene side, vil en bedømmelse kun kunne tage højde for, hvad der er inkluderet i en rapport. På den anden side, vil en bedømmer værdsætte at rapporten kun indholder væsentlig information og er kort og præcis. Et nyttigt råd er, at hvis man er i tvivl om en sætning eller et afsnit skal med, så kan man prøve at slette det, og se om teksten lider alvorlig skade deraf. Gør god brug af referencer og citationstegn Hvis man benytter sig af teoremer eller ideer, som andre har publiceret skal man lave en nøjagtig reference til pågældende publikation. Hvis man låner sætninger, afsnit eller figurer fra andre publikationer, skal man sikre sig, at disse ikke er beskyttet af kopirettigheder. I den virkelige verden indbefatter det, at man oftest skal kontakte det relevante forlag for at bede om lov til en gengivelse. Det er en dødssynd sidestillet med eksamenssnyd at kopiere tekst, uden at skrive det i citationstegn og uden en præcis reference. Rapportopgaver på Datalogisk Institut er ikke at sidestille som en publikation, og det kan derfor accepteres, at der gengives tekst og figurer, når blot der angives en nøjagtig reference til hvorfra det er lånt. Læs korrektur Typisk vil rapporten være kulminationen på lang tids arbejde, og det er let at afsætte for lidt tid til skriveprocessen. Men husk at rapporten er et produkt i sig selv. Så vær her opmærksom på, om der står hvad I mener, og ikke hvad I tror der står. Et godt råd er, at bede en der ikke har 2

skrevet teksten eller dele deraf til at læse korrektur. Det kan også være en god ide at bruge en højtlæsningsprøve: Bed kæresten eller en ven om at læse teksten højt for dig. Det behøver ikke at være nogen med forstand på emnet. Ved at lytte til flowet i højtlæsningen, og evt. bede om at få genfortalt, hvad vedkommende har læst højt, så vil man hurtigt finde ud af, hvor teksten fungerer eller er usammenhængende. Tillad en rigelig stor margin og nummerér alle sider fortløbende En bedømmer vil typisk have brug for at gøre noter, og det er som regel nemmest at skrive i marginen. Gør derfor plads til dette. Desuden, rapporter skal typisk afleveres uden indbinding, så sørg derfor for at alle sider har fortløbende sidenumre, ifald nogen skulle tabe rapporten under læseprocessen. 3 Rapportskabelon Der kan ikke gives en entydig skabelon for at hvordan en rapport skal bygges op, men en opgave består typisk af en forside, en indledning, et analyse- og designkapitel, et kapitel om programmeringsovervejelser, en beskrivelse af afprøvningen og en konklusion. Indholdet af disse kunne være: Forside Alle rapporter, der afleveres, skal have en forside. Forsiden skal som minimum indeholde rapportens titel og dens forfattere. Som oftest er der fortrykte forsider, der blot skal udfyldes. Forord Et forord er et godt sted at skrive lidt om rammerne for opgaven, såsom til hvilket kursus opgaven hører, særlige ydre omstændigheder osv., men undlad ynk. Indledning Hvad handler opgaven om, og evt. hvad er jeres mål for succes? Skriv kort hvad jeres krav til læseren er f.eks. at vedkommende har kendskab til opgaveteksten, gennemgået pensum, osv. Mange bruger også indledningen til at foregribe problemer og resultater. Endelig husk, at indledningen skal give læseren den røde tråd gennem rapporten, og skal kunne fungere (næsten) selvstændigt sammen med konklusionen. Analyse og design Dette er et meget vigtigt kapitel, da forfatterne her har mulighed for at illustrere hvordan teoretiske problemer er blevet analyseret og løst. Det er vigtigt at kapitlet indeholder en afbalanceret beskrivelse af delproblemer, som skal løses, og at der er diskuteres fordele og ulemper ved mulige designvalg. Generelt er det en god ide at afslutte kapitlet med en kort opsummering af krav til løsningen både dem stillet i opgaven, og dem som I evt. selv har tilføjet. Det vil give jer noget konkret at forholde jer til i konklusion. 3

Programmeringsovervejelser og programbeskrivelse I analysekapitlet er overordnede problemer og løsningsmuligheder grundigt blevet diskuteret. En rapport ved Datalogisk Institut vil næsten altid omfatte en efterfølgende implementation. Implementationen vil ofte give anledning til yderligere praktiske overvejelser, som oftest beskrives i dette kapitel: Hvilke problemer er der, hvordan kan de løses og hvordan har I valgt at løse dem? Lad være med at bruge megen spalteplads på problemer, der kun har en besvarelsesmulighed. Mange benytter sig i sådanne kapitler af pseudokode, dvs. en program stump skrevet i et til lejligheden defineret sprog, som f.eks. et C-lignende sprog. Pas i det tilfælde på, at sådanne pseudokodestumper ofte kan misforstås, idet programmeringssproget oftest ikke er veldefineret. Afprøvning Afprøvning er en meget vigtig del af programudvikling. Det er op til jer at overbevise læseren, at I har en løsning uden graverende fejl og mangler. Det er vigtigt, at I afprøver alle afkroge af jeres program, og dette gøres typisk ved at gå løsningen igennem både indenfor rammerne af almindelig brug og i grænsetilfælde. Eksempelvis, hvis man har skrevet en divisionsfunktion, så kunne det være relevant at afprøve division af alle 4 kombinationer af positive og negative tal både med store og små tal i absolut forstand, og tilsidst at afprøve division med 0 som grænsetilfældet. Det er en god ide, at opstille delafprøvninger slavisk efter (fysikrapport-) skabelonen: Hvad er formålet, forsøgsopstillingen, det forventede resultat, uddata og konklusionen på delafprøvningen. Det er naturligvis målet at lave så fejlfri kode som muligt, men da der næsten altid er tidsmæssige begrænsninger, er det vigtigt, at dokumentere eventuelle fejl i løsningen, som man ikke kan nå at rette, og såvidt muligt at påpege hvordan man kunne rette fejlene. Konklusion Konklusionen samler op på det arbejde I har lavet. Ligesom indledningen er det en god ide, at skifte fokus så konklusionen både forholder sig til særligt problematiske eller succesfulde resultater men også en mere overordet beskrivelse af de opnåede resultater og identificerede problemer. F.eks. hvad er resultatet af opgaven? Har I opnået det I ville? Har I opfyldt de krav I satte i jeres kravspecifikation? Konklusionen er ikke et sted at tilføje ny viden, men samler op på det I har skrevet, og til at foreslå videre fremtidigt arbejde. 4 Brug L A TEX Hvis man ikke allerede har et tekstbehandlingsprogram, anbefales L A TEX. L A TEX er ikke et WYSIWYG, hvilket frarøver forfattere mulighed for at bekymre sig om opsætning, for derimod at fokusere på den logiske opbygning af sin tekst. Det er en fordel, da opsætning først er rigtigt relevant hen mod slutningen af 4

skriveprocessen. L A TEX er beskrevet i Kursusbog 2 Vejledning i brug af DIKUs EDB-system [1]. Kapitel 8 og 9 er nyttige og specielt i afsnit 9.4 kan man finde fine eksempler på, hvordan man løser de mest almindelige rapportrelaterede opgaver i L A TEX. En anden god introduktion til L A TEX er [2]. Begge bøger kan læses elektronisk og er godt til opslag, men det kan bedre betale sig at købe bøgerne trykt end at printe dem selv. Den tidligere nævnte skabelon for en rapport ser ud som følger i L A TEX: \documentclass{article} \usepackage{isolatin1} \usepackage[danish]{babel} \usepackage{graphicx} \usepackage{url} \title{g-opgave i Maskinarkitektur} \author{rune Andresen og Jon Sporring} \begin{document} \maketitle \section{forord} Skriv lidt om de ydre omstændigheder. \section{indledning} Definer opgavens rammer, og mål, osv. f.eks.\ til \LaTeX\ \cite{lshort}. Huske passende henvisninger som \section{analyse og design} Gennemgå beslutninger på et teoretisk niveau. \section{programmeringsovervejelser og programbeskrivelse} Beskriv implementationsdetaljer her. % Figurer er nyttige, men husk referencer f.eks.\ til % Figur~\ref{fig:myfirstfigure}. %\begin{figure} % \centering % \resizebox{0.4\textwidth}{!}{ % \includegraphics{myfavoritepostscriptfigure.ps}} % \caption{en sigende figurtekst.} % \label{fig:myfirstfigure} %\end{figure} \section{afprøvning} Husk at lave en grundig afprøvning. 5

\section{konklusion} Saml op på hvor I startede, hvad I har gjort og lært, og mulige forbedringer af jeres system. \begin{thebibliography}{99} \bibitem{lshort} Tobias Oetiker: The Not So Short Introduction to \LaTeX\ $2_{\varepsilon}$, \newline \url{http://www.ctan.org/tex-archive/info/lshort/english/lshort.pdf} \newline Kan købes i Universitetsbogladen, 110kr. \end{thebibliography} \end{document} Litteratur [1] Kursusbog 2: Vejledning i brug af DIKUs EDB-system, http://www.diku.dk/it-systemerne/vejledninger/kb2.html Kan købes i Studieadministrationen på DIKU, 80kr. [2] Tobias Oetiker: The Not So Short Introduction to L A TEX 2 ε, http://www.ctan.org/tex-archive/info/lshort/english/lshort. pdf Kan købes i Universitetsbogladen, 110kr. 6