8.5 Dokumentasjon og presentasjon

Kode ingen forstår er verdiløs

Du kan ha skrevet verdens mest elegante løsning, men hvis ingen – inkludert deg selv om seks måneder – forstår hva den gjør og hvordan den brukes, har du et problem. Dokumentasjon er det som gjør kode og prosjekter forståelige. Som regelen sier: «Kode forteller datamaskinen hva den skal gjøre. Dokumentasjon forteller mennesker hva koden gjør.» Det finnes flere typer: brukerdokumentasjon (for sluttbrukere), teknisk dokumentasjon (for utviklere), prosessdokumentasjon (om utviklingsprosessen) og API-dokumentasjon.

Det aller viktigste dokumentet er README-filen – prosjektets visittkort, det første folk ser på GitHub. En god README bør inneholde prosjektnavn og en kort beskrivelse, gjerne et skjermbilde, installasjonsinstruksjoner steg for steg, bruksanvisning med eksempler, hvilke teknologier som er brukt, bidragsytere og lisens. For skoleprosjekter kan du også ta med hvilke kompetansemål prosjektet dekker og en refleksjon over hva du lærte.

README-filer og mye annen dokumentasjon skrives i Markdown – et lettvekts formateringsspråk som er lesbart både som ren tekst og som formatert output. Du lager overskrifter med #, fet tekst med **stjerner**, punktlister med bindestrek, lenker med [tekst](url), og kodeblokker med tre backticks. Markdown brukes overalt: på GitHub, i Notion, Slack, Discord og Jupyter Notebooks – et essensielt verktøy for alle som jobber med teknologi.

Kommenter hvorfor, ikke hva

Kodekommentarer er tekst i kildekoden som datamaskinen ignorerer, men som hjelper mennesker. I Python kommenterer du med #, i JavaScript med //, i HTML med <!-- --> og i CSS med /* */. Men ikke alle kommentarer er nyttige – dårlige kan faktisk gjøre koden vanskeligere å forstå. Den gylne regelen er: forklar hvorfor, ikke hva. En kommentar som x = x + 1 # Øker x med 1 er verdiløs, fordi koden allerede viser det. Derimot er x = x + 1 # Kompenserer for 0-indeksering i API-responsen nyttig, fordi den forklarer en ikke-opplagt grunn.

Flere tommelfingerregler: oppdater kommentarene når koden endres (utdaterte kommentarer er verre enn ingen), bruk beskrivende variabelnavn i stedet for å kommentere dårlige navn, kommenter kompleks logikk som algoritmer og formler, og marker midlertidige løsninger med # TODO.

Utover README og kommentarer trenger større prosjekter teknisk dokumentasjon rettet mot utviklere som skal vedlikeholde koden. Den bør dekke systemarkitekturen (hvordan prosjektet er organisert, hvilke filer som gjør hva, gjerne vist som et filtre), dataflyten gjennom systemet, hvilke API-er som brukes, kjente begrensninger og feil, og installasjonskrav. I et skoleprosjekt viser teknisk dokumentasjon læreren at du faktisk forstår systemet du har bygd.

Prosess og presentasjon

I IT 1 vurderes du ikke bare på det ferdige produktet, men også på prosessen. Prosessdokumentasjon viser hvordan du planla, jobbet og reflekterte underveis. Den bør inneholde en prosjektplan (mål, brukerhistorier, MVP, tidsplan), en designprosess (wireframes, designvalg og begrunnelser, brukertesting), en utviklingslogg (hva ble gjort hver uke, hvilke utfordringer oppstod og hvordan de ble løst), og en refleksjon (hva fungerte, hva du ville gjort annerledes, hva du lærte). Gode råd: skriv litt underveis i stedet for alt på slutten, ta skjermbilder av viktige steg, vær ærlig om utfordringer – det viser refleksjonsevne – og knytt arbeidet til kompetansemålene.

Til slutt må du kunne presentere arbeidet ditt. En god prosjektpresentasjon har struktur: en introduksjon (hva er problemet, hva har du laget, for hvem), en demo der du viser produktet i aksjon, en teknisk gjennomgang (teknologier og et interessant kodeutdrag), en prosessdel (planlegging, utfordringer, læring), og en avslutning. De viktigste tipsene: vis, ikke fortell – demonstrer at noe er enkelt i stedet for å påstå det; hold det enkelt og vis bare de mest interessante kodedelene; forbered demoen og ha en backup som skjermbilder hvis noe svikter; snakk om utfordringene, for de problemene du løste er ofte det mest interessante; tilpass språket til publikum; og unngå å lese fra lysbildene – de er visuell støtte, ikke manuskriptet ditt.

Oppsummering

Kode ingen forstår er verdiløs – derfor er dokumentasjon så viktig. README-filen er prosjektets visittkort, skrevet i det lettvekts formateringsspråket Markdown. Kodekommentarer skal forklare hvorfor, ikke hva, og holdes oppdaterte.

Større prosjekter trenger teknisk dokumentasjon om arkitektur og dataflyt, og i IT 1 er prosessdokumentasjon sentral – planlegging, designvalg, utviklingslogg og refleksjon, helst skrevet underveis. Til slutt må du kunne presentere prosjektet med tydelig struktur, der du viser produktet i aksjon, forklarer valgene dine og deler utfordringene du løste. Med dette har du verktøyene til å gjøre arbeidet ditt forståelig – og synlig – for andre.