Teknisk rapportskrivning - en kortfattad handledning Thomas Larsson Institutionen för datateknik (IDt) Mälardalens högskola 5 oktober 1999 Västerås Skicka gärna synpunkter och kommentarer till thomas.larsson@mdh.se Ingen berättelse är så bra att den inte kan förstöras då den berättas. - ordspråk
Sammanfattning En mycket viktig del i en teknologs arbete är att dokumentera sitt arbete, ofta i form av att skriva rapporter. Det har emellertid visat sig att det ofta finns stora brister hos teknologer när det gäller att uttrycka sig i tal och skrift. Det finns därför ett behov av övning i kombination med handledning i ämnet teknisk rapportskrivning. Detta dokument syftar till att ge en introduktion till ämnet. En ofta använd generell mall för rapporter presenteras och förklaras, del för del. Denna mall kan användas för såväl vetenskapliga artiklar, som för andra tekniska rapporter eller uppsatser. Förutom att rapporternas uppbyggnad och utformning diskuteras, ges också en del råd angående rapportplanering och språkbruk. Teknisk rapportskrivning sida 2 Thomas Larsson
Innehållsförteckning 1. INLEDNING 4 2. RAPPORTENS UPPBYGGNAD 4 3. RAPPORTENS INLEDANDE DEL 4 3.1 TITELBLADET 4 3.2 SAMMANFATTNINGEN 5 3.3 FÖRORDET 5 3.4 INNEHÅLLSFÖRTECKNING 5 4. RAPPORTENS HUVUDDEL 5 4.1 INLEDNINGEN 5 4.2 AVHANDLINGEN 5 4.3 SLUTSATSER 6 5. RAPPORTENS REFERENSDEL 6 5.1 REFERENSER 6 5.2 BILAGOR 6 6. YTTERLIGARE NÅGRA RÅD PÅ VÄGEN 7 6.1 BÖRJA I TID 7 6.2 SPRÅKBRUK 7 6.3 VAL AV SPRÅK 7 6.4 LÄR AV ANDRA 7 7. SLUTSATSER 7 REFERENSER 8 BILAGOR A. VANLIGA SPRÅKFEL Teknisk rapportskrivning sida 3 Thomas Larsson
1. Inledning Att skriva en bra rapport är en konst. Denna enkla skrift syftar endast till att ge en grundläggande beskrivning av hur en teknisk rapport generellt sett bör skrivas och struktureras. Den riktar sig till personer som ej är så erfarna på att skriva rapporter. Mycket mer information när det gäller konsten att skriva, allmänt sett, ges t.ex. av Strömqvist i [Ström94]. När det gäller hur vetenskapliga artiklar och rapporter skrivs så behandlas detta mer utförligt av t.ex. Zobel i [Zobel97]. Den sistnämnda boken inriktar speciellt på hur artiklar inom ämnet datavetenskap skrivs. Rekommendationerna som följer i detta dokument är naturligtvis inte absoluta utan måste i många fall anpassas efter ämne och den typ av rapport som önskas. Först beskrivs hur rapporter vanligtvis är uppdelade i olika avsnitt och sedan beskrivs vilken typ av innehåll som är lämpligt i de olika avsnitten. Avslutningsvis ges lite allmänna råd om rapportplanering och språkbruk. 2. Rapportens uppbyggnad Följande generella mall visar hur en rapport eller en vetenskaplig artikel ofta kan vara uppbyggd. Det är i vissa fall inte nödvändigt att ha med alla dessa delar och i andra fall kanske ytterligare någon punkt borde läggas till, beroende på vilken sorts rapport det gäller. Inledande del titelblad sammanfattning förord innehållsförteckning Huvuddel inledning avhandling slutsatser Referensdel referenser bilagor När en rapport huvudsakligen är uppbyggd enligt detta välbekanta och väl beprövade mönster så känner läsarna med all säkerhet igen sig och de kan snabbt hitta det de söker efter. 3. Rapportens inledande del 3.1 Titelbladet Ett titelblad kan naturligtvis se ut på många olika sätt. Det är dock viktigt att det attraherar läsaren och identifierar rapporten. Vanligtvis innehåller titelbladet åtminstone följande information: titel författare och utgivare ort och datum Tänk på att titeln skall vara framträdande och upplysande, men ändå så kort som möjligt. Om titeln är misstänkt lång kan den delas upp i en huvud- och undertitel. En väl vald bild kan också placeras på titelbladet. Den kan ge positiv uppmärksamhet åt rapporten. Övrig information som kan placeras på titelbladet är t.ex. information om eventuella handledare, om arbetet utförts på någon viss kurs och/eller linje, adress och telefonnummer till utgivaren samt författarens e-postadress. Teknisk rapportskrivning sida 4 Thomas Larsson
3.2 Sammanfattningen Sammanfattningen skall utgöra ett kortfattat sammandrag av hela rapporten och den skrivs därför lämpligen när rapporten i övrigt är färdig. Tänk på att sammanfattningen måste väcka intresse för ämnet. Den bör beskriva vad som gjorts, vilka slutsatser som dragits och betydelsen av dessa. Kom också ihåg att det ska vara möjligt att läsa sammanfattningen helt fristående från den övriga rapporten. 3.3 Förordet Om ett förord skall skrivas eller ej är valfritt. I ett förord är det lämpligt att information beskrivs som inte har med rapportens övriga innehåll att göra, t.ex. hur rapporten har kommit till, varför rapporten har skrivits och vem som har finansierat projektet. Det är också vanligt att författaren tackar för den hjälp och uppmuntran som olika personer har bidragit med under arbetets gång. Förordet brukar skrivas under med skribentens namn. 3.4 Innehållsförteckningen Innehållsförteckningen skall ge ett klar uppfattning om rapportens innehåll, dess omfattning och struktur och den ska naturligtvis ge läsaren hjälp att hitta de olika avsnitten i rapporten på ett smidigt sätt. 4. Rapportens huvuddel 4.1 Inledningen I inledningen definieras problemet eller uppgiften tydligt. En introduktion till ämnet ges och bakgrunden till arbetet beskrivs. Vidare skall syftet med arbetet och målsättningen med det tydligt beskrivas. Det kan också vara lämpligt att beskriva redan existerande lösningar på likartade problem, tillsammans med fördelar och nackdelar med dessa. Inledningen bör också ge en beskrivning av resten av rapportens uppbyggnad och det arbetssätt och de metoder som använts. Det kan ibland vara lämpligt att dela upp det som här nämnts i flera olika avsnitt med egna underrubriker. 4.2 Avhandlingen Avhandlingen utgör själva grundstommen i rapporten. Här beskrivs det arbete som har utförts på ett mer detaljerat sätt. Följande punkter visar vad som ofta bör beskrivas i avhandlingen: Uppgift, arbetsätt och utförande Metoder, algoritmer och datastrukturer som använts Experiment, prestanda etc. Vilka resultat som uppnåtts och hur de motiverats Om rapporten beskriver ett programvaruutvecklingsprojekt så bör avhandlingen naturligtvis innehålla all relevant information enligt den metod som följts under arbetets gång. Typiskt är dock att det skall finnas avsnitt som utförligt beskriver följande aktiviteter: Analys Design Implementation Testning Teknisk rapportskrivning sida 5 Thomas Larsson
Den färdiga källkoden brukar man inte i sin helhet ta med i själva avhandlingen, men det kan ofta vara lämpligt att ha med den som en bilaga till rapporten. Tänk på att källkoden bör vara kommenterad på ett lämpligt sätt, så att den kan läsas någorlunda enkelt av en person som inte deltagit i själva programmeringen. 4.3 Slutsatser Rapportens huvuddel avslutas med ett avsnitt där arbetet värderas. Vilka begränsningar finns i er lösning? Vilka fördelar respektive nackdelar har den? Har målet med arbetet nåtts? I vilka sammanhang kan lösningen tillämpas? Det kan också vara lämpligt att beskriva möjligheter till en framtida fortsättning på arbetet och vilka förbättringar som är önskvärda. Detta kan också beskrivas i ett eget avsnitt, t.ex. under rubriken framtida arbete, som då bör placeras före avsnittet slutsatser. 5. Rapportens referensdel 5.1 Referenser Det finns flera olika standarder för hur referenser skall skrivas. Vilken man än använder så är det viktigt att åtminstone tillräcklig information finns med. Vilken information som behövs beror på vad det är man refererar till. Hör följer den information som brukar anges för några olika typer av källor: Bok: författare, titel, förlag, ISBN-nummer, årtal, (sidor) Tidskrift: författare, titel, tidskrift, nr, årtal, (sidor) Rapport: författare, titel, ursprung, årtal, (sidor) Alla referenser brukar vanligtvis räknas upp sist i en rapport. Det är också lämpligt att rapportens text verkligen hänvisar till alla uppräknade referenser. Ett bra sätt att i rapporten referera till sina referenser är att använda s.k. prefix. Här följer ett exempel på en liten del av ett stycke där denna teknik används och efteråt visas själva referenserna som det refereras till i stycket: Boyse [Boyse79] beskriver en metod som kan användas för att avgöra om en punkt befinner sig inuti en generell polygon eller inte och Vince [Vince95] beskriver en lösning på samma problem, men för det enklare specialfallet där polygonen är en triangel. Referenser: [Boyse79] [Vince95] J.W Boyse, Interference decision among solids and surfaces, Communications of the ACM, Vol. 22, No. 1, pages 3-9, 1979. John Vince, Virtual Reality Systems, Addison-Wesley Publishing Company, ISBN 0-201-87687-6, 1995 5.2 Bilagor All den information som inte får plats eller passar in i själva rapporten, men som ändå är relevant för läsaren, kan placeras som bilagor. Det kan t.ex. vara bevis, formler, testdata, statistik och diagram som kanske är skrymmande eller alltför detaljerade för den typiske läsaren. Om rapporten utgör dokumentationen till ett program kan det t.ex. vara lämpligt att ha både källkoden och en användarmanual till det utvecklade programmet som bilagor. Om sådant material infogades i rapportens huvudsakliga text så skulle det kunna förstöra ett annars naturligt och angenämt informationsflöde. Teknisk rapportskrivning sida 6 Thomas Larsson
6. Ytterligare några råd på vägen 6.1 Börja i tid Något som det kan vara lätt att glömma bort är att det tar tid att skriva rapporter. Se därför till att det finns gott om tid till arbetet med rapporten. För att underlätta skrivandet bör arbetet dokumenteras fortlöpande. Skriv ned vad som lästs, vilka experiment som utförts, resultat som erhållits, problem som dykt upp etc. Skaffa en projektpärm redan från början där allt sådant material kan samlas. Annars är det lätt att viktiga data, tankar och resonemang går förlorade. 6.2 Språkbruk För att rapporten inte skall orsaka onödiga negativa reaktioner hos läsarna måste den hålla en hög språklig standard. Är t.ex. språket i rapporten anpassat efter den tilltänkta målgruppen? Är det grammatiskt korrekt? Finns det brister i stavning och ordval? Är rapporten logiskt utformad? Man behöver inte var något språkligt geni för att åstadkomma en rapport som ger ett positivt intryck, är väl genomarbetad och redigerad. Använd de hjälpmedel som finns för t.ex. stavning i dagens ordbehandlare. Låt en eller ett par personer korrekturläsa rapporten och komma med synpunkter på såväl språkliga som innehållsmässiga förbättringar. Läs dock alltid igenom rapporten själv först, helst dagen efter den har skrivits. 6.3 Val av språk Många tekniska termer på engelska saknar vedertagna översättningar till det svenska språket. När en rapport innehållande information av teknisk karaktär skall skrivas så uppstår därför ofta frågan: Vilket språk skall dokumentet skrivas på? Om rapporten skrivs på svenska så kanske var och varannan mening i slutänden kommer att innehålla något engelsk begrepp. I sådana fall kanske det är bättre att välja att skriva hela rapporten på engelska. Men rapportskrivandet blir vanligtvis betydligt svårare om man inte skriver på sitt modersmål. Hur skriver man korrekt och smakfull engelska? För att lära sig detta krävs naturligtvis övning och handledning. Framför allt så bör lämpliga ordböcker och grammatikböcker finnas lätt tillgängliga när tveksamheter om vad som är korrekt infinner sig. Förutom detta, så rekommenderas den kortfattade men innehållsrika boken [Strun79], som ger många bra råd och tips när det gäller den språkliga stilen. 6.4 Lär av andra Var inte rädd för att fråga andra personer om råd. Att be några personer, kanske med lite olika bakgrund, att komma med synpunkter på ditt skrivande, kan visa sig vara mycket effektivt. Ett annat bra sätt att lära sig skriva bättre rapporter är att studera andras verk. Välj ut, eller be någon annan lämplig person rekommendera, några bra rapporter, helst inom det aktuella ämnesområdet. 7. Slutsatser De enkla råd som här getts har förhoppningsvis bidragit med en del praktiska tips som kan vara till nytta när rapporter skrivs. Att skriva en bra rapport kan visserligen vara krävande och mödosamt, men om resultatet blir bra är det väl värt besväret. Låt aldrig ett väl utfört arbete fördunklas av en dåligt skriven rapport. Teknisk rapportskrivning sida 7 Thomas Larsson
Referenser [Ström94] Siw Strömqvist, Konsten att tala och skriva, Gleerups förlag, ISBN 91-40-61629-0, 1994 [Zobel97] J. Zobel, Writing for Computer Science, Springer-Verlag, ISBN 981-3083-22-0, 1997 [Strun79] William Strunk Jr. and E. B. White, The Elements of Style, Third Edition, Allyn & Bacon, ISBN 0-205-19158-4, 1979 Teknisk rapportskrivning sida 8 Thomas Larsson
Bilaga A A: Vanliga språkfel Att skriva korrekt svenska är svårt. Det finns många språkliga fallgropar som man måste se upp för. Här följer endast en kortfattad diskussion gällande några få vanliga språkliga problem. Många gånger behöver man betydligt mer omfattande hjälp. Svenska akademiens ordlista är t.ex. ett utmärkt redskap i många situationer. A.1 Särskrivning Ord som är sammansatta skall i det svenska språket skrivas ihop. I engelskan får man däremot bilda sammansättningar genom att skriva två ord bredvid varandra. Men på svenska heter det t.ex. kollisionsdetektering och klassdiagram, inte kollisions detektering och klass diagram. Ibland kan särskrivning t.o.m. förändra innebörden i texten. Lägg märke till skillnaden mellan följande uttryck: rök fritt eller rökfritt sjuk gymnastik eller sjukgymnastik Som en hjälp för att avgöra om ord skall skrivas ihop eller ej så läs texten högt. Om det då låter som ett ord, så skriv det som ett ord, och om det låter som två ord, så skriv det som två ord. Det finns även vissa ord som både kan särskiljas och skrivas ihop. Exempel på sådana ord är över huvud taget, allt mer, förresten och såtillvida. A.2 Förkortningar När det gäller förkortningar, så finns det i huvudsak två olika stilar som man kan välja, nämligen med punkter och utan punkter. Några exempel på de förstnämnda är: t.ex., bl.a., m.m., t.o.m., s.k. Samma förkortningar kan också skrivas enligt den andra stilen med punkterna utbytta mot mellanrum. De ser då ut enligt följande: t ex, bl a, m m, t o m, s k Det finns också förkortningar som aldrig har någon punkt. Bland dess kan nämnas: jfr, ca Ett annat tillvägagångssätt är naturligtvis att inte använda några förkortningar alls. Det är bekvämt för läsaren om alla ord skrivs ut. Vilken stil man än väljer så bör man naturligtvis vara konsekvent inom samma dokument. I tekniska rapporter används ofta områdesspecifika förkortningar, t.ex. de som kommer från dataområdet, såsom PC, CPU och USB. Dessa förkortningar skrivs ofta med versaler. Nackdelen med dessa förkortningar är naturligtvis att de lätt kan vålla läsaren onödiga problem med att förstå texten. En god vana kan därför vara att åtminstone visa vad förkortningen står för genom att skriva ut hela begreppet första gången det dyker upp i texten, t.ex. så här: Universial Serial Bus (USB). Teknisk rapportskrivning sida 9 Thomas Larsson
A.3 Stor eller liten bokstav Ord som alltid inleds med stor bokstav i det svenska språket är egennamn och namn på platser såsom: André, Asien, Stockholm, Mälaren, Anundshög, Mellansverige, Mälardalens högskola Däremot så inleds veckodagar, månader och avdelnings- och språkangivelser med liten bokstav: måndag, juni, västeråsare, engelska Teknisk rapportskrivning sida 10 Thomas Larsson