8.5 Dokumentasjon og presentasjon

Dokumentasjon og presentasjon

Kode som ingen forstår er verdilaus. Du kan ha skrive den mest elegante løysinga i verda, men dersom ingen – inkludert deg sjølv om seks månader – kan forstå kva ho gjer og korleis ho vert brukt, har du eit problem.

Dokumentasjon er det som gjer kode og prosjekt forståelege. Det handlar om å skrive ned det som ikkje er opplagt frå koden sjølv: kva prosjektet gjer, kvifor det er laga slik, korleis ein installerer og bruker det, og kva ein bør vite for å kunne jobbe vidare med det.

Presentasjon er like viktig – du må kunne formidle arbeidet ditt til andre. Anten det er læraren din, medelevar, eller ein framtidig arbeidsgjevar, må du kunne forklare kva du har laga, kva val du tok og kvifor.

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

README – visittkortet til prosjektet

README-fila er det aller viktigaste dokumentet i prosjektet ditt. Det er det fyrste folk ser på GitHub, og det bør gi all informasjon som trengst for å forstå og bruke prosjektet.

Kva bør ein god README innehalde?

1. Prosjektnamn og kort skildring – Kva gjer prosjektet? Éi til to setningar.

2. Skjermbilete eller demo – Vis korleis det ser ut. Eit bilete seier meir enn tusen ord.

3. Installasjon – Steg-for-steg-instruksjonar for korleis ein set opp prosjektet lokalt.

4. Bruk – Korleis bruker ein prosjektet? Eksempel er gull verdt.

5. Teknologiar – Kva språk, rammeverk og verktøy er brukte?

6. Bidragsytarar – Kven har jobba med prosjektet?

7. Lisens – Kva rettar har andre til å bruke koden?

For skuleprosjekt kan du òg inkludere:
- Læreplankompetansemål prosjektet dekkjer
- Prosessdokumentasjon (lenkje til prosjektlogg)
- Refleksjon over kva du har lært

Markdown – enkelt tekstformat

README-filer og mykje anna dokumentasjon vert skrivne i Markdown – eit lettvektsformateringsspråk som er laga for å vere lesbart både som rein tekst og som formatert output.

Dei viktigaste Markdown-elementa

# Overskrift nivå 1
## Overskrift nivå 2
### Overskrift nivå 3

**Fet tekst** og *kursiv tekst*

- Punktliste
- Element to
- Element tre

1. Nummerert liste
2. Element to
3. Element tre

[Lenketekst](https://www.eksempel.no)

![Bildetekst](bilde.jpg)

\`Inline kode\`

\`\`\`python
# Kodeblokk med syntaksutheving
print("Hei verden!")
\`\`\`

> Sitat eller merknad

| Kolonne 1 | Kolonne 2 |
|-----------|-----------|
| Data 1    | Data 2    |

Markdown vert brukt overalt: GitHub (README, issues, pull requests), Notion, Slack, Discord, Jupyter Notebooks og mange andre stader. Det er eit essensielt verktøy for alle som jobbar med teknologi.

Kodekommentarar – forklar kvifor, ikkje kva

Kodekommentarar er tekst i kjeldekoden som vert ignorert av datamaskina men hjelper menneske med å forstå koden. Men ikkje alle kommentarar er nyttige – dårlege kommentarar kan faktisk gjere koden vanskelegare å forstå.

Korleis skrive kommentarar i ulike språk

# Python: Enkeltlinje-kommentar med #
x = 10  # Kommentar på slutten av en linje

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

<!-- HTML-kommentar -->

/* CSS-kommentar */

Dårlege kommentarar

# Dårlig: Sier hva koden gjør (åpenbart fra koden selv)
x = x + 1  # Øker x med 1
navn = input("Navn: ")  # Henter input fra brukeren
liste.sort()  # Sorterer listen

Gode kommentarar

# Bra: Forklarer HVORFOR, ikke hva
x = x + 1  # Kompenserer for 0-indeksering i API-responsen

# Bra: Forklarer en ikke-opplagt beslutning
# Bruker bubblesort i stedet for quicksort fordi listen
# alltid er under 20 elementer, og bubblesort er enklere å feilsøke
sorter_manuelt(liste)

# Bra: Varsler om en begrensning
# OBS: Fungerer bare for norske postnumre (4 siffer)
def valider_postnummer(postnummer):
    return len(postnummer) == 4 and postnummer.isdigit()

Tommelfingerreglar for kommentarar

1. Forklar kvifor, ikkje kva – Koden viser kva som vert gjort; kommentaren forklarer kvifor
2. Oppdater kommentarar når koden vert endra – Utdaterte kommentarar er verre enn ingen kommentarar
3. Bruk skildrande variabelnamn i staden for å kommentere dårlege namn
4. Kommenter kompleks logikk – Algoritmar, formlar og ikkje-opplagt kode
5. Marker mellombelse løysingar med TODO-kommentarar: # TODO: Bytt til databaselagring

Teknisk dokumentasjon for utviklarar

Teknisk dokumentasjon går djupare enn README-fila og er retta mot utviklarar som skal jobbe med eller vedlikehalde koden. I eit skuleprosjekt viser teknisk dokumentasjon læraren at du forstår systemet du har bygd.

Kva bør teknisk dokumentasjon dekkje?

Systemarkitektur: Korleis er prosjektet organisert? Kva filer gjer kva? Korleis heng delane saman?

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: Korleis flyt data gjennom systemet? Frå inputen til brukaren til vising av resultat.

API-bruk: Kva eksterne tenester bruker prosjektet? Kva slags data vert henta og sendt?

Kjende avgrensingar: Kva fungerer ikkje enno? Kva kjende feil finst? Kva ville du forbetra med meir tid?

Installasjonskrav: Kva verktøy og versjonar trengst for å køyre prosjektet?

Prosessdokumentasjon – vis at du forstår prosessen

I IT 1 vert du ikkje berre vurdert på det ferdige produktet, men òg på prosessen. Prosessdokumentasjon viser korleis du planla, jobba og reflekterte undervegs.

Element i prosessdokumentasjon

Prosjektplan:
- Kva er målet med prosjektet?
- Kva brukarhistorier definerte vi?
- Kva er MVP-en?
- Tidsplan med milepælar

Designprosess:
- Wireframes og skisser (tidlege versjonar)
- Designval og grunngjevingar (kvifor valde vi desse fargane, denne layouten?)
- Prototypar og brukartesting (kva lærte vi?)

Utviklingslogg:
- Kva vart gjort i kvar sprint/veke?
- Kva utfordringar oppstod?
- Korleis vart dei løyste?
- Kva tok lengre tid enn venta?

Refleksjon:
- Kva fungerte bra i prosjektet?
- Kva ville du gjort annleis?
- Kva har du lært?
- Korleis fungerte samarbeidet (dersom gruppeprosjekt)?

Tips for prosessdokumentasjon

- Skriv litt undervegs i staden for alt på slutten
- Ta skjermbilete av wireframes, prototypar og viktige steg
- Ver ærleg om utfordringar – det viser refleksjonsevne
- Knyt arbeidet til kompetansemål frå læreplanen

Presentere IT-prosjekt

Å kunne presentere arbeidet ditt er ein viktig ferdigheit. I IT 1 vil du truleg presentere prosjekt for klassen eller læraren. Her er nokre prinsipp for gode presentasjonar.

Struktur for ein prosjektpresentasjon

1. Introduksjon (1-2 min): Kva er problemet? Kva har du laga? For kven?
2. Demo (3-5 min): Vis produktet i aksjon. Lat det snakke for seg sjølv.
3. Teknisk gjennomgang (2-3 min): Kva teknologiar brukte du? Korleis er koden organisert? Vis eit interessant kodeutdrag.
4. Prosess (2-3 min): Korleis planla du prosjektet? Kva utfordringar møtte du? Kva lærte du?
5. Avslutning (1 min): Kva ville du gjort med meir tid? Spørsmål?

Gode presentasjonstips

Vis, ikkje fortel: I staden for å seie «Nettsida er brukarvenleg», vis det ved å demonstrere at det er enkelt å utføre ei oppgåve.

Hald det enkelt: Ikkje vis all koden – vel ut dei mest interessante eller utfordrande delane. Publikum treng ikkje sjå 500 linjer HTML.

Førebu demo: Test alt på førehand. Ha ein backup-plan dersom noko ikkje fungerer (skjermbilete, video av demoen).

Snakk om utfordringar: Dei mest interessante delane av eit prosjekt er ofte problema du løyste. Ikkje ver redd for å dele kva som var vanskeleg.

Tilpass for publikum: Læraren vil sjå at du forstår konsepta. Medelevar vil sjå noko kult. Tilpass språkbruken etter kven du snakkar til.

Unngå å lese frå lysbilete: Lysbileta er visuell støtte, ikkje manuskriptet ditt. Bruk stikkord og bilete, ikkje lange tekstblokker.

Oppsummering

I dette kapittelet har du lært:

- Dokumentasjon: skriftleg info som forklarer eit prosjekt.
- README: visittkortet til prosjektet.
- Markdown: enkelt tekstformat for dokumentasjon.
- Kodekommentarar: forklar kvifor, ikkje kva.
- Presentasjon: strukturert munnleg og visuell formidling.

Noekkelbegreper