8.5 Dokumentasjon og presentasjon

Dokumentasjon og presentasjon

Kode som ingen forstår er verdiløs. Du kan ha skrevet den mest elegante løsningen i verden, men hvis ingen – inkludert deg selv om seks måneder – kan forstå hva den gjør og hvordan den brukes, har du et problem.

Dokumentasjon er det som gjør kode og prosjekter forståelige. Det handler om å skrive ned det som ikke er åpenbart fra koden selv: hva prosjektet gjør, hvorfor det er laget slik, hvordan man installerer og bruker det, og hva man bør vite for å kunne jobbe videre med det.

Presentasjon er like viktig – du må kunne formidle arbeidet ditt til andre. Enten det er læreren din, medelever, eller en fremtidig arbeidsgiver, må du kunne forklare hva du har laget, hvilke valg du tok og hvorfor.

I dette kapittelet lærer du å skrive gode README-filer, kommentere kode på en nyttig måte, lage teknisk dokumentasjon, og presentere IT-prosjekter på en overbevisende måte.

README – prosjektets visittkort

README-filen er det aller viktigste dokumentet i prosjektet ditt. Det er det første folk ser på GitHub, og det bør gi all informasjon som trengs for å forstå og bruke prosjektet.

Hva bør en god README inneholde?

1. Prosjektnavn og kort beskrivelse – Hva gjør prosjektet? Én til to setninger.

2. Skjermbilde eller demo – Vis hvordan det ser ut. Et bilde sier mer enn tusen ord.

3. Installasjon – Steg-for-steg-instruksjoner for hvordan man setter opp prosjektet lokalt.

4. Bruk – Hvordan bruker man prosjektet? Eksempler er gull verdt.

5. Teknologier – Hvilke språk, rammeverk og verktøy er brukt?

6. Bidragsytere – Hvem har jobbet med prosjektet?

7. Lisens – Hvilke rettigheter har andre til å bruke koden?

For skoleprosjekter kan du også inkludere:
- Læreplankompetansemål prosjektet dekker
- Prosessdokumentasjon (lenke til prosjektlogg)
- Refleksjon over hva du har lært

Markdown – enkelt tekstformat

README-filer og mye annen dokumentasjon skrives i Markdown – et lettvekts formateringsspråk som er designet for å være lesbart både som ren tekst og som formatert output.

De viktigste Markdown-elementene

``markdown


Overskrift nivå 1

\Inline kode\

\\\python

Kodeblokk med syntaksutheving

Kodekommentarer – forklar hvorfor, ikke hva

Kodekommentarer er tekst i kildekoden som ignoreres av datamaskinen men hjelper mennesker med å forstå koden. Men ikke alle kommentarer er nyttige – dårlige kommentarer kan faktisk gjøre koden vanskeligere å forstå.

Hvordan skrive kommentarer i ulike språk

``python


Python: Enkeltlinje-kommentar med #

`javascript
// JavaScript: Enkeltlinje-kommentar
/ JavaScript: Flerlinjekommentar
som kan gå over
flere linjer /
`

`html

`

`css
/ CSS-kommentar /
`

Dårlige kommentarer

`python


Dårlig: Sier hva koden gjør (åpenbart fra koden selv)

`python


Bra: Forklarer HVORFOR, ikke hva

1. Forklar hvorfor, ikke hva – Koden viser hva som gjøres; kommentaren forklarer hvorfor
2. Oppdater kommentarer når koden endres – Utdaterte kommentarer er verre enn ingen kommentarer
3. Bruk beskrivende variabelnavn i stedet for å kommentere dårlige navn
4. Kommenter kompleks logikk – Algoritmer, formler og ikke-opplagt kode
5. Marker midlertidige løsninger med TODO-kommentarer: # TODO: Bytt til databaselagring`

Teknisk dokumentasjon for utviklere

Teknisk dokumentasjon går dypere enn README-filen og er rettet mot utviklere som skal jobbe med eller vedlikeholde koden. I et skoleprosjekt viser teknisk dokumentasjon læreren at du forstår systemet du har bygd.

Hva bør teknisk dokumentasjon dekke?

Systemarkitektur: Hvordan er prosjektet organisert? Hvilke filer gjør hva? Hvordan henger delene sammen?

``
prosjekt/
├── index.html # Forside
├── css/
│ └── style.css # Alle stiler
├── js/
│ ├── main.js # Hovedlogikk og event handlers
│ ├── api.js # API-kall til Yr
│ └── utils.js # Hjelpefunksjoner
├── images/ # Bilder og ikoner
└── README.md # Prosjektdokumentasjon
``

Dataflyt: Hvordan flyter data gjennom systemet? Fra brukerens input til visning av resultat.

API-bruk: Hvilke eksterne tjenester bruker prosjektet? Hva slags data hentes og sendes?

Kjente begrensninger: Hva fungerer ikke ennå? Hvilke kjente feil finnes? Hva ville du forbedret med mer tid?

Installasjonskrav: Hvilke verktøy og versjoner trengs for å kjøre prosjektet?

Prosessdokumentasjon – vis at du forstår prosessen

I IT 1 vurderes du ikke bare på det ferdige produktet, men også på prosessen. Prosessdokumentasjon viser hvordan du planla, jobbet og reflekterte underveis.

Elementer i prosessdokumentasjon

Prosjektplan:
- Hva er målet med prosjektet?
- Hvilke brukerhistorier definerte vi?
- Hva er MVP-en?
- Tidsplan med milepæler

Designprosess:
- Wireframes og skisser (tidlige versjoner)
- Designvalg og begrunnelser (hvorfor valgte vi disse fargene, denne layouten?)
- Prototyper og brukertesting (hva lærte vi?)

Utviklingslogg:
- Hva ble gjort i hver sprint/uke?
- Hvilke utfordringer oppstod?
- Hvordan ble de løst?
- Hva tok lengre tid enn forventet?

Refleksjon:
- Hva fungerte bra i prosjektet?
- Hva ville du gjort annerledes?
- Hva har du lært?
- Hvordan fungerte samarbeidet (hvis gruppeprosjekt)?

Tips for prosessdokumentasjon

- Skriv litt underveis i stedet for alt på slutten
- Ta skjermbilder av wireframes, prototyper og viktige steg
- Vær ærlig om utfordringer – det viser refleksjonsevne
- Knytt arbeidet til kompetansemål fra læreplanen

Presentere IT-prosjekter

Å kunne presentere arbeidet ditt er en viktig ferdighet. I IT 1 vil du sannsynligvis presentere prosjekter for klassen eller læreren. Her er noen prinsipper for gode presentasjoner.

Struktur for en prosjektpresentasjon

1. Introduksjon (1-2 min): Hva er problemet? Hva har du laget? For hvem?
2. Demo (3-5 min): Vis produktet i aksjon. La det snakke for seg selv.
3. Teknisk gjennomgang (2-3 min): Hvilke teknologier brukte du? Hvordan er koden organisert? Vis et interessant kodeutdrag.
4. Prosess (2-3 min): Hvordan planla du prosjektet? Hvilke utfordringer møtte du? Hva lærte du?
5. Avslutning (1 min): Hva ville du gjort med mer tid? Spørsmål?

Gode presentasjonstips

Vis, ikke fortell: I stedet for å si «Nettsiden er brukervennlig», vis det ved å demonstrere at det er enkelt å utføre en oppgave.

Hold det enkelt: Ikke vis all koden – velg ut de mest interessante eller utfordrende delene. Publikum trenger ikke se 500 linjer HTML.

Forbered demo: Test alt på forhånd. Ha en backup-plan hvis noe ikke fungerer (skjermbilder, video av demoen).

Snakk om utfordringer: De mest interessante delene av et prosjekt er ofte problemene du løste. Ikke vær redd for å dele hva som var vanskelig.

Tilpass for publikum: Læreren vil se at du forstår konseptene. Medelever vil se noe kult. Tilpass språkbruken etter hvem du snakker til.

Unngå å lese fra lysbilder: Lysbildene er visuell støtte, ikke manuskriptet ditt. Bruk stikkord og bilder, ikke lange tekstblokker.