Denne PDF er et eksempel på dokumentation i form af en synopsis af et meget lille projekt “Sten-Saks-Papir”.
Bemærk: Den måde der er valgt at dokumentere på i denne synopsis er kun et eksempel. Udvælg selv de dokumentationsformer der er relevante for netop det produkt som du skal skrive en synopsis til. Fx indeholder eksemplet ikke pseudokode, klassediagrammer eller begrundelse for valg af biblioteker.
Eksemplet er fremstillet vha. Quarto som kan bruges til at skrive dokumenter vha. markdown (formatet som vi bruger til logbog) mm. At skrive tekniske tekster i rå tekst har mange fordele, se fx [1, Kap. 16], [2].
Denne skabelon kan bruges som udgangspunkt til egen synopsis.
Vejledning til skrivning af synopsis
Til prøver skal der, udover programmet, afleveres dokumentation i form af en synopsis på 5-8 normalsider eksklusiv koder, rutediagrammer, bilag mm. Denne er individuelt udarbejdet. Ved prøver får man ikke feedback på synopsen før den mundtlige prøve.
1 Det er især vigtigt, at man skriver om sin egen del af koden i den detaljerede del af dokumentationen. Få diagrammer, der gælder koden overordnet, kan dog godt udarbejdes fælles i gruppen.
Sprogmodeller (såsom chatGPT) må aldrig bruges til at skrive synopsis, rapporter e.l.
VIGTIGT!!!: Husk tydeligt at markere i synopsen hvis noget af koden i produktet er lånt direkte fra en anden kilde! Hvis dette er udeladt er der tale om plagiat!
Forslag til opbygning
En synopsis kan opbygges i følgende afsnit. Anbefalet sidelængde for hvert afsnit er angivet i parentes (i normalsider). Bemærk at bjælkerne nedenfor kan foldes ud for at se vejledning til hvert afsnit.
Synopsens forside hvor man ofte vælger at indsætte et relevant billede (evt. af programmet).
Skal indeholde information om:
- Titel
- Fag
- Navn
- Klasse
- Skole
- Afleveringsdato
- Øvrige gruppemedlemmer
Kort resume (opsummering) af hele synopsens indhold, hvilket inkluderer udfordringen, hvad der dokumenteres, test/afprøvning og hvilke resultater der blev opnået.
Indholdsfortegnelse med sideangivelse for resten af synopsens afsnit.
Giv læseren en kort introduktion til hvad der er blevet arbejdet med i projektet og som dokumenteres i resten af synopsen. Beskriv arbejdsfordelingen i gruppen. Beskriv resten af synopsens struktur.
Beskriv hvordan du har brugt trinvis forbedring til at udvikle programmet. Kom med konkrete eksempler fra udvinklingsarbejdet og relater til forskellige dele af metoden (planlægning, udarbejdelse og evaluering) samt de forskellige typer af forbedringer (forfinelse, udvidelse og omstrukturering).
Beskriv hvordan programmet bruges og hvad det kan udføre. Altså programmets funktionalitet herunder indtastningsmuligheder (styring), og skærmlayout. Brug gerne skærmbilleder.
Lav en overordnet beskrivelse af programmet som giver læseren et overblik over programmets opbygning. Det indebærer den overordnede logik/flow og struktur herunder filstruktur.
Dokumenter udvalgte dele af programmet detaljeret med indsatte kodebidder. Den detaljerede dokumentation kan laves i underafsnit og skal afspejle hvad du selv har fokuseret på i projektet. Man kan frit vælge, men det er ofte oplagt, at dokumentere funktioner eller klasser. Man må gerne fjerne mindre relevante dele (fx kommentarer eller gentagelser).
Husk at bruge fagudtryk fx om variabler, datatyper og funktioner. Brug diagrammer og/eller tabeller til at understøtte den overordnede beskrivelse og den detaljerede dokumentation. Diagrammer kan fx være rutediagrammer, klassediagrammer eller funktionskaldsdiagrammer. Sørg helst for at have min. 2 forskellige typer af diagrammer til kildekoden.
Dokumentationen skal være en beskrivelse af koden. Man opnår dog højere niveau hvis programmeringsmæssige overvejelser indgår i beskrivelsen. Det indbefatter valg om logik og struktur der er truffet i udviklingen af programmet. Det kan være relevant i både den overordnede og i den detaljerede del.
Der kan både beskrives hvordan programmet er blevet løbende testet samt hvordan det er blevet afprøvet til sidst.
Afsnittet kan opdeles i funktionelle test og brugertest.
Beskriv hvordan funktionelle resultater blev verificeret. Nogle dele skal helst være mere målbart end visuel bekræftelse. Det kan fx være verificering af variablers værdier under kørsel af programmet.
Konkluder på synopsen ved at svare på spørgsmålene i problemformuleringen. Perspektiver til fremtidigt arbejde dvs. hvordan programmet kunne videreudvikles.
Angiv kilder brugt under udviklingen af programmet også selvom det kun er brugt som inspiration.
Kode til repository kan også angives som kilde. Sørg for at det er tilgængeligt for lærer.
Hvis der er angivet link til repository i kildelisten er det ikke nødvendigt at indsætte kildekoden som bilag.
Bilag kan også indeholde ekstra dokumentation som der ikke er plads til i selve rapporten. Det kan fx være større eller flere udgaver af diagrammer, testresultater, brugervejledninger.
Indsættelse af kildekode i synopsis
- Quarto: include-code-files.
- Word: Kildekode kan kopieres fra VScode og linjenumre kan indsættes under “layout” (nummerering kan begrænses til markeret tekst under indstillinger).
Tilbage til toppenReferencer
[1]
D. Thomas og A. Hunt, The Pragmatic Programmer: Your Journey To Mastery, 20th Anniversary Edition (2nd Edition). Addison-Wesley Professional, 2019.
[2]
D. Tenen og G. Wythoff,
“Sustainable Authorship in Plain Text using Pandoc and Markdown”,
Programming Historian, bd. 3, 2014, Tilgængelig hos:
https://doi.org/10.46430/phen0041