DIKU-blad 3.4: Vejledning i udformning af rapporter
Dette er udgave 1 af en vejledning skrevet af Peter Naur, dateret 28. september 1976. Eventuelle fejl i teksten skyldes sikkert slåfejl ved indtastningen, ligesom der er sket lettere tilpasning af den oprindelige teksts formatering, så den passer til den brugt i denne wiki.
Sigte og begrundelse
Nærværende vejledning er tænkt som rettesnor for al udformning af tekniske rapporter med tilknytning til DIKU. Her tænkes såvel på de studerendes projektbesvarelser, lige fra datalogi 0 til specialet, som på medarbejdernes projektrapporter og afhandlinger. Vejledningen indledes med nogle ord om de synspunkter der ligger bag den. Herefter følger et afsnit om rapporters indhold, et om termer og deres stavning, og et om rapporters form. Vejledningen er udformet som konkrete regler, der støttes af bemærkninger og illustrationer taget fra datalogistuderendes arbejder.
Som begrundelse for den vægt der igennem denne vejledning lægges på udformningen af skriftlige arbejder skal først og fremmest anføres at skriftlig argumentation bør anses for central ved alt arbejde på universitetsniveau. Gennem den skriftlige form får såvel forfatteren som læseren mulighed for at fordybe sig i indviklede problemer, uden at være begrænset af udmatning. Forfatteren kan gennem en lang række arbejdsperioder udvikle sin argumentation til det yderste han eller hun formår, i retning af klarhed og fuldstændighed. Tilsvarende kan læseren tilegne sig argumentationen i mindre dele ad gangen, og i sit eget tempo.
Hertil kommer, som yderligere begrundelse, at rapportudformning er af særlig betydning i datalogien, af følgende grunde:
- De datamatiske systemer, hvis udformning er så central i datalogien, vil i de fleste tilfælde omfatte et program der stadig spiller nært sammen med en kreds af personer, såsom brugere, operatører, andre programmer, og forfatteren selv. Kontakten mellem programmet og denne personkreds må for en stor del formidles gennem dokumentation i form af rapporter. Herigennem får rapporter en vigtig plads i datamatiske systemer af praktisk talt enhver art.
- Udarbejdelsen af en rapport om et konstruktionsprojekt, f.eks. en datamatisk systemudvikling, vil ofte virke direkte fremmende for projektets kvalitet, blot gennem den systematiske eftertænksomhed som rapportudformningen forudsætter.
Det er svært at skrive gode rapporter. Den færdighed som studenterne har tilegnet sig gennem skolearbejdets stileskrivning er utilstrækkelig som grundlag, selv hvor skolens arbejde er lykkedes fuldt ud.Der savnes såvel færdighed i at organisere et stort stof, som færdighed i at udforme tankegange der er betinget af et samspil mellem specielle, tekniske begreber.
Problemerne omkring sproglig udformning af videnskabelig litteratur er så betydningsfulde at de har været genstand for systematiske studier i såvel nationale som internationale videnskabelige organisationer. Som eksempel kan nævnes at UNESCO står som udgiver af en rapport der er oversat til dansk og udgivet af Udvalget for Videnskabelig og Teknisk Information og Dokumentation (DANDOK) under titlen RETNINGSLINIER FOR UDFORMNING AF VIDENSKABELIGE ARTIKLER. Fra denne indledning kan hentes følgende formålserklæring: "En videnskabelig artikel tilsigter først og fremmest at udbrede tanker og oplysninger på klar, kortfattet og redelig måde." Dette sigte bør kunne overtages uændret ved al rapporterudarbejdelse der er tænkt på i denne vejledning. Mange af UNESCOs retningslinier er følgelig benyttet i det følgende.
Rapporters indhold
Forud for de nedenstående regler om selve rapportudformningen er det på sin plads at bringe en vejledning i disse reglers brug:
Lad tilegnelsen af de nærværende regler foregå ved en løbende vekslen mellem praktisk rapportudformning og studium af de vejledende regler. Vend tilbage til vejledningen forud for udformningen af hver ny rapport.
Det fulde indhold af regler af den art som gives nedenfor kan kun forstås på baggrund af egne, personlige oplevelser af de problemer der opstår ved udformningen og brugen af større rapporter. For den uerfarne kan reglerne virke banale eller uvæsentlige. Kun den der selv har kæmpet med problemerne ved hvor skoen trykker.
De regler der gennemgås nedenfor kan alle forståes ud fra hensynet til læseren. For hver enkelt regel gælder det, at såfremt den tilsidesættes vil der i bedste fald kræves en særlig indsats fra den læser der vil forstå rapporten; i værste fald vil det være umuligt for læseren at forstå rapporten.
Start såvel hele rapporten som hvert større afsnit med en god indledning som kan vække læserens interesse: sig tidligt, kort og klart hvem teksten henvender sig til; hvad teksten drejer sig om, hvad der er det væsentlige i den, hvad der er grunden til at læseren bør kunne interessere sig for den. Giv en oversigt over teksten.
Ved rapporter der mangler en klar indledende redegørelse for det væsentlige får læseren den fornemmelse at forfatteren ikke selv har gjort sig klart hvad der er det væsentlige. Dertil er det irriterende som læser at blive præsenteret for detaljer, altså småting, hvis betydning i en større sammenhæng er ukendt. Det er urimeligt at forlange at læseren skal uddrage det væsentlige i et arbejde ved at gennemsøge en mængde detaljer.
Eksempel 1. Dårlig rapportindledning
Umiddelbart efter titelblad og indholdsfortegnelse følger:
1. Brugervejledning.
Programmet, der er en model til simulering af jobstrømproblemet i et operativsystem, er skrevet i SIMULA 67 og indkørt på RECKUs UNIVAC 1110 anlæg.
1.1 Inddata
Programmet kan simlere en række jobstrømproblemer, alt afhængig af de af brugeren givne inddata.
Der skal først være 4 kort, som skal angive følgende oplysninger:
Eksempel 1 bør sammenlignes med indledningen til nærværende vejledning, som er forsøgt udformet efter den anbefalede retningslinie.
Gør rapporten let tilgængelig for hele dens naturlige læserkreds: Gør rede for alle konkrete omstændigheder der har betydning for læserens forståelse, herunder arbejdets forbindelser til dets ydre rammer, f.eks. institutioner, datamatiske systemer eller andre projekter. Anslå hellere læserens forudsætninger for lavt end for højt.
Ved kursusarbejder må formuleringen vælges ud fra en antagen naturlig læserkreds, idet den faktiske læsekreds, læsere og censorer, er urimelig snæver, og dertil har forudsætninger, der normalt går adskilligt ud over forfatterens . Som antagen læserkreds ved kursusarbejder kan rimeligt vælges studerende i samme fag, som studerer ved et andet universitet, og som endnu kun er nået til det studietrin,som forfatteren tilbagelagde et år forud.
Eksempel 1 ovenfor viser mangler efter denne regel. Der tales om "jordstrømsproblemet" uden forklaring. Der tales om "programmet" og "4 kort" uden tilstrækkelig forberedelse.
Tilstræb klarhed i den sproglige udformning: brug så vidt muligt enkelt, naturligt sprog; vær opmærksom på hvert ords præcise betydning og sørg for at denne betydning helt svarer til den mening der skal udtrykkes. Sørg for at hvert ord bringer en mening som rummer noget konkret nyt i sammenhængen; undgå vage almindeligheder. Opbyg sætningerne således at de klart udsiger meningen; sørg for at de er opbygget i nøje overensstemmelse med sprogets logik. Undgå ualmindelige forkortelser, slang og sprogbrug de rkun forstås af mindre kliker; følg sædvanlig retskrivning.
Uklarhed i den sproglige udformning syne softe at hænge sammen med at forfatteren har kastet sig ud i længere og mere komplicerede sætninger end han eller hun har kunnet magte. Undgå derfor lange sætninger; det gør det også lettere for læseren.
Eksempel 2. En lang sætning, der strider imod sprogets logik:
"En hopsætning afbryder den normale sekvens af operationer, defineret ved opskrivningsrækkefølgen af sætningerne ved at definere dens efterfølger explicit ved den angivne etikette skal forekomme i sted i programmet, men hvor er ligegyldigt."
Eksempel 3. Vage almindeligheder:
"Der anføres nogle konstruktive forslag til forbedring af forskellige forhold."
Eksempel 4.
"... at det kunne være interessant at bruge [visse data] til at lave statistikker over de studerendes forbrug, dels for at se hvor omhyggelige de studerendes opgørelser var, og dels..."
Ordet "statistikker" er her upræcist, et mere træffende ord er "oversigter". Ordet "omhyggelige" strider imod sprogets logik; personer kan være omhyggelige, opgørelser ikke.
Eksempel 5. Forkert ordvalg:
"En hopsætning ændrer rækkefølgen af de sætninger, der udføres, idet der fortsættes med sætningen lige efter det sted i programmet, hvor labelnavnet er erklæret."
Miseren her er ordet "ændrer", som udsiger at noget bliver anderledes. Dette er imidlertid en misvisende måde at beskrive hopsætninger.
Slang og klikesprog er ikke primært egnet til at formidle oplysninger og tanker, men til at bekræfte forfatterens tilhørsforhold til en gruppe. I en teknisk-videnskabelig rapport virker de forstyrrende vd at indføre et element som er sagen uvedkommende og bør derfor undgås. Af lignende grund bør man i sådanne rapporter benytte sædvanlig, upåfaldende retskrivning.
Eksempel 6. Klikesprog og afvigende stavning:
"Det ses at indkøringen begyndte for alvor 26/11, og så er der ellers kul på frem til afleveringen 8/12."
"...de skal selvfølgelig osse indgå i overvejelserne."
Såvel "kul på" som "osse" virker påfaldende.
Hold nøje rede på de begreber der er brug for i rapporten, og på de betegnelser der bruges for dem. Under planlægningen af rapporten bør begreberne omhyggeligt vælges. I rapporten selv bør begreberne indføres ved en forklaring eller definition forud for at de bruges. Tekniske betegnelser bør kun bruges uden forklaring hvis de har vundet bred, almindelig anerkendelse. Efter at begreberne er indført i rapporten må de fastholdes gennem at der fortsat benyttes samme betegnelser for dem.
Eksempel 7. Klikesprog og afvigende stavning:
1.8 Label sætning.
En labelerklæring er en identifier efterfulgt af kolon (:) og bevirker, at der sættes et mærke (en label) i rækkefølgen af sætninger som skal udføres. En label er knyttet til GOTO sætninger og benyttes som hopmærke for GOTO.
Figur 4.
eks. på labelerklæring.
statement:
-
Hoplog: labelerklæring
Statement;
GOTO hoplog;
En identifier der bruges som LABEL må ikke være erklæret som INTEGER, BOOLEAN eller TEXT. Da man betragter en label der mødes første gang, som en erklæring. En labelerklæring behøves ikke at være erklæret før man skriver GOTO LABEL.
I dette eksempel er der begrebsforvirring og uklarhed i hver eneste sætning. Det kan bl.a. bemærkes at overskriftens udanske betegnelse "label sætning" (udansk hvis skrevet i to ord) slet ikke forklares eller bruges. Man må gætte sig til at det der betegnes "label" er den identifier der optræder i en labelerklæring. Sætningen der begynder "Da man betragter..." er usproglig. Den sidste sætning, "En labelerklæring...", kan tjene som mønster på sproglig ubehjælpsomhed.
Termer og deres stavning
Rapporter på dansk bør fortrinsvis benytte danske termer i overensstemmelse med de ordlister der indgår i datalogistudiet. Hvor det skønnes hensigtsmæssigt kan den tilsvarende engelske term tilføjes i parentes første sted termen bruges, for eksempel således: "linieskriver (eng. line printer)". Som alternativ kan anvendes engelske termer, men disse skal da overalt hvor de bruges markeres med citationstegn, for eksempel: "line printer". Også ved denne form skal der benyttes anbefalede termer, hvor sådanne står til rådighed. En blanding af anbefalede danske termer uden citationstegn og anbefalede engelske termer med citationstegn kan også benyttes.
Visse retskrivnings- og terminologifejl forekommer så hyppigt i Datalogisk Instituts rapporter at der her skal gøres særligt opmærksom på dem:
- På dansk kan man let og bekvemt danne sammensatte ord ved at skrive bestanddelene sammen, uden blanktegn, f.eks. "gemmesætning", "hopadresse", "linieskriver". Ved opremsninger af flere sammensatte ord, hvor den ene bestanddel er uændret, bruges bindestreg, f.eks. "ind- og uddata", "hopsætninger og -ordrer". Der er imod dansk sprogbrug at følge engelsk, der ikke tillader denne lette sammensætning af ord, men til gengæld i vid udstrækning tillader sammenstilling af ord, med bevarelse af det adskillende blanktegn.
- Følgende ord giver meget hyppigt anledning til fejl: aritmetisk, adjektiv der betegner det der vedrører aritmetik, skrives følgelig med kun ét r, og slutter "tisk"; inddata er den danske term der svarer til engelsk "input" som substantiv; linieskriver er den danske term der svarer til engelsk "printer" eller "line printer"; parentes staves således, dvs. med kun ét a og e som fjerde bogstav; tegn er den korte, bekvemme term der svarer til engelsk "character" (ikke sjælden træffes et terminologisk roderi bestående af "tegnsæt" og "karakter" sid eom side); uddata er den danske term der svarer til engelsk "output" som substantiv; udførelse er den danske term der svarer til engelsk "execution", og bør ikke erstattes hverken af "udførsel" (som svarer til "eksport") eller "eksekvering".
Rapporters form
I de nedenstående regler skelnes mellem primærrapporter, dvs. sådanne rapporter som er fremkommet direkte gennem forfatterens arbejde i et enkelt eksemplar, herunder de studerendes projektbesvarelser, og reproduktionsrapporter, dvs. rapporter som er fremkommet gennem en renskrivning af primærrapporter, normalt med en mangfoldiggørelse for øje. Hvor intet andet angives gælder reglerne for såvel primær- som reproduktionsrapporter.
Rapporter skal skrives på papir i formatet A4, dvs. 210 mm bret og 297 mm højt. Ved primærrapporter bør kun den ene side af papiret bruges.
Primærrapporter bør kun skrives på den ene side af papiret for at gøre det muligt at foretage rettelser ved klipning, se nedenfor.
Teksten skal holdes inden for en spaltebredde af 155 mm. Til højre og venstre vil der således blive en margen af ca. 27 mm. Forneden skal der ligeledes holdes en margen af ca. 27 mm. Foroven skal den egentlige tekst holde en afstand af ca. 27 mm fra papirkanten. Inden for denne afstand kan skrives sidetal og identifikation af teksten.
Den fri margen tjener flere forskellige praktiske formål: den giver plads for læserens noter og rettelser; den gør det muligt at sammenholde bladene i for eksempel ringbind; og den gør det muligt at fotokopiering kan ske med en mindre kritisk håndtering af bladene, uden fare for at noget af den egentlige tekst går tabt.
Rapporter skal skrives på maskine. Teksten skal stå klart og let læseligt. Skrivemaskinen bør være udstyret med et frisk farvebånd og dens typer være rene. Enkelte tegn der ikke findes på skrivemaskinen kan tilføjes med håndskrift. Dette bør dog så vidt muligt undgås, gennem at tilpasse tegnbrugen til den anvendte skrivemaskine. Undtagelsesvis kan det tillades at bogstavet "l" benyttes som ciffer ét (1) og bogstavet "O" som ciffer nul (0), dog kun under forudsætning af at a) det gøres systematisk gennem hele rapporten, b) der gøres en tydelig anmærkning derom, gerne som en fremtrædende notits på det sted hvor den har størst betydning, og c) alle steder hvor forveksling kan tænkes at ske markeres særligt, f.eks. ved en fodnote.
Maskinskrift er langt lettere at læse end håndskrift. Under udarbejdelsen af en rapport kommer dette også forfatteren til gode.
Primærrapporter skal skrives med dobbelt linieafstand. Derved bliver der plads til rettelser af begrænset omfang, som kan indføres i den fri plads mellem to linier. Reproduktionsrapporter skal skrives med enkelt linieafstand, hvor ikke særlige hensyn, specielt til formler med indekser, eksponenter og lign., gør en større afstand nødvendig.
Valget af linieafstand begrundes ud fra en grov, økonomisk betragtning. Ved primærrapporter er det hensynet til bekvemmeligheden ved rettelser der er udslagsgivende.
Tekstens afsnit markeres ved at første linien begynder med 5 blanktegn.
Denne regel svarer til den praksis der i århundreder har været fulgt ved det meste bogtryk.I de senere år har der været en tendens til at adskille afsnit med en fuld blank linie, med det nye afsnit begyndende helt til venstre. Denne reger er mindre økonomisk med pladsen end den gamle, og har dertil andre betydelige ulemper: Markeringen af et nyt afsnits begyndelse først på en ny side, og ved skrivning med dobbelt linieafstand overalt, er utydelig; der er stor risiko for at omskrivning eller ombrydning af teksten bevirker at afsnitsdelinger forsvinder.
Den angivne regel gælder kun for tekster i sædvanlig prosa. Reglen er ikke bindende ved skrivning af mere specielle tekster. For eksempel bør der ved linier hvori der forekommer formler med indekser og potenser, for eksempel Apq, benyttes større linieafstand, således at alle tegn går klart fri af hinanden. Tabellignende opstillinger bør udformes specielt i hvert enkelt tilfælde. Det anbefales at man prøver sig frem for at opnå den størst mulige klarhed og overskuelighed. Herunder bør det huskes at brugen af megen fri plads, altså hvidt papir, ikke i sig selv bevirker klarhed og overskuelighed. Under alle omstændigheder bør de ovenfor givne regler om papirformat og margenbredder overholdes. Hvad angår de mange vanskellige spørgsmål om udformning og opstilling af formler og programmer henvises til bilaget.
Primærrapporter kan fremstilles ved rettelser og sammenklipning efter følgende retningslinier. Rettelser skal udføres som følger: Al den gyldige tekst skal være maskinskrevet og skal under sædvanlig læsning være at finde langs den løbende linie eller i den fri linie umiddelbart ovenover. Tekstens forløb skal underlæsningen fremgå helt klart umiddelbart. Hvis der kan være tvivl om hvor en tilføjelse der er skrevet i en fri linie skal indsættes, bør der anvendes vejledende, håndskrevne streger. Den gyldige tekst skal være uden rettelser i form af tegn der er skrevet oven i hinanden Tegn og tekst der er kasseret under skrivningen skal dækkes til fuldstændig ulæselighed med tykke, sorte streger. Tekst der er fjernet på denne måde kan bestå af enkelte tegn midt i ord, af enkelte ord, ellers af længere passager. Den færdige tekst kan være opstået ved en sammenklipning af mindre brudstykker. Brudstykkerne skal holdes sammen med gennemsigtigt klæbebånd. Dette kan anvendes på papirets bagside, og i højre og venstre margen på forsiden. Ingen tekst må være dækket af klæbebånd. Den færdige, sammenklippede tekst skal følge de sædvanlige regler om format, margen osv.
Den bekvemmelighed hvormed rettelser og ændringer af teksten kan foretages har stor betydning for selve tekstudarbejdelsen, og derigennem for kvaliteten af den færdige rapport. En god rapport vil normalt være resultatet af en lang bearbejdningsproces, med talrige rettelser og reorganiseringer af teksten. De givne regler sigter imod at gøre ændringer bekvemme at foretage, uden at det i alt for høj grad sker på bekostning af rapportens udseende og øvrige brugbarhed.
Den første side af en rapport bør angive: forfatterens fulde navn, dato for udfærdigelsen, identifikation af sagens sammenhæng, f.eks. kursus og institution, sagens titel, indholdsfortegnelse med sidetal (indholdsfortegnelsen kan dog iudelades ved meget korte rapporter). Alle sider, inklusive bilag, skal forsynes med fortløbende sidenumre.
Disse regler turde alle være af indlysende betydning for læserens bekvemmelighed.
Rapportbedømmelse
De ovenfor givne retningslinier bør givetvis indgå i grundlaget for bedømmelsen af rapporter inden for DIKUs rammer. Normalt vil der hertil komme andre krav, som er knyttet til bestemte former for rapporter. Som vejledning og støtte for bedømmelsen af visse former for rapporter er der udfærdiget bedømmelsesskemaer, som på kort form præciserer visse krav. Hvilke skemaer der foreligger lkan til enhver tid ses i DIKU-blad 1.1, Oversigt over DIKU-blade.
Bilag: Speciel typografi
Formler og programmer
Ved valget af formen for formler og programmer vil det være hensigtsmæssigt at lade sig lede af de krav der stilles til manuskripter der skal sættes til bogtryk. Disse krav kan findes udtrykt i forskellige tidsskrifters vejledning til forfattere, f.eks. i "BIT - Guide for authors", København 1975. Ved bogtryk af formler og programmer gøres der udstrakt brug af kursiv og fed sats. I maskinskrevne manuskripter kan disse typeformer markeres med hanholdsvis enkel og dobbel understreg.
Eksempel: (Comm. ACM 16 (Dec. 1973), 763)
if x < 1 then
begin
f[1] := f1(x,d);
for n := 1 step 1 untill nmax - 1 do
f[n+1] := (1 - x * f[n])/n;
go to exit
end;
Nummerering af kapitler, afsnit, formler m.v.
Kapitler nummereres 1, 2, 3, ... og hvert kapitel kan opdeles i flere afsnit (f.eks. 1.2, 1.3, ...), der atter kan videreopdeles i underafsnit (f.eks. 3.3.1, 3.3.2, ...). Der advares dog mod at drive systematikken for vidt; at finde et stykke tekst med overskriften
3.2.2.2.1.2.1.2 Nulelimination
i en artikel omfattende ialt 18 trykte sider, virker snarere komisk end velovervejet, og bør ikke være eksempel til efterfølgelse.
Formler og udtryk, der ønskes fremhævet, bør udskilles fra den omgivende tekst med 1-1 1/2 blank linie foroven og forneden samt indledes med 5 blanktegn. Eksempel:
Rp = (apM + Rp+1) * 0.9985 * upM + ∑M-1j=1 apj * upj (24)
hvor upj er den noterede børskurs for obligationer udstedt i periode p..."
Formler nummereres i højre side som vist. For hvert kapitel starter nummereringen forfra: (1), (2), ... . Det samme gælder nummereringen af eventuelle figurer, sætninger, eksempler og opgaver.
Henvisninger: "... af (24) ses ..." betyder: "Af udtryk (24) i det kapitel hvori henvisningen forekommer ses". Ved henvisning til et udtryk i et andet kapitel skrives f.eks.: "... af (3-24) ses ...", hvorved der refereres til udtryk (24) i kapitel 3.
I tidsskriftartikler (eller arbejder, der i omfang kan sidestilles hermed) er det ofte praksis at opfatte hele artiklen som et enkelt kapitel. Det vil i denne sammenhæng sige, at formler, figurer, sætninger m.v. nummereres fortløbende, samt at afsnit nummereres som nævnt for kapitler (1,2, ...) og underafsnit som afsnit (1.2, 1.2, ...).
Litteraturhenvisninger
Litteraturfortegnelsen angives samlet til slut efter de egentlige kapitler/afsnit, men før eventuelle bilag. Fortegnelsen sorteres alfabetisk efter førstnævnte forfatters efternavn, f.eks.
Parkas, J (1902), "Ûber die Theorie der einfachen Ungleichungen", Journal fûr die reine und angewandte Mathematik 124, 1-27
Gomory, R.E. (1958-1), "Essentials of an Algorithm for Integer Solutions to Linear Programs", Bull. Amer. Math. Soc., 64 (5)
Gomory, R.E. (1958-2), "An Algorithm for Integer Solutions to Linear Programs", Princeton-IBM Mathematics Research Project, Technical Report No. 1
Hadley, G. (1964), "Nonlinear and Dynamic Programming", Addison-Wesley Publishing Co., Reading, Massachusetts, Inc.
Kantorovich, L.V. (1939), Mathematicheske metody organizatsii planirovania proizvodstva, Leningrad University, Leningrad. (Translated as: "Mathematical methods in the organization and planning of production", Management Science, 6 (1960), 366-422)
Kuhn, H.W., and A.W. Tucker (1950), "Nonlinear Programming", in J. Neuman (ed), Proceedings of the Second Berkeley Symposium on Mathematical Statistics and Probability, University of California Press, Berkeley, California
Eksempler på litteraturhenvisninger: "... Hadley (1964) udtaler herom ..."; "... og et formelt bevis er bl.a. angivet i (Gomory 1958-2) ...".