Skriv en README der faktisk bliver læst

Jeg opdagede først hvor dårlig mine egne READMEs var, da en ven skrev: “Jeg vil gerne prøve dit projekt, men hvad skal jeg gøre efter git clone?”. Jeg havde lavet alt koden, men ikke én linje om, hvordan man kørte den. Klassisk.

Hvis du kan genkende den situation, så er det her til dig.

Hvad en god README skal kunne i praksis

En README er ikke pynt. Det er brugsvejledningen til dit repo.

For mig skal en god README kunne tre ting:

• Forklare hvad projektet gør, og hvem det er til
• Gøre det muligt at køre projektet lokalt uden at gætte
• Give et hurtigt overblik til rekrutterere, medstuderende og evt. contributers

Forestil dig en travl censor, en potentiel arbejdsgiver eller en medstuderende, der bare skal kunne:

• Se om projektet er relevant på 10 sekunder
• Køre det på 2 minutter
• Se hvordan koden er bygget op på 5 minutter

Det er den oplevelse, vi bygger README-skabelonen efter.

README skabelon til GitHub (til studie- og portfolio-projekter)

Nedenfor får du en github README skabelon, som passer godt til typiske projekter: små webapps, APIer, skoleopgaver, hobbyværktøjer osv.

Du kan kopiere den direkte ind i en README.md og tilpasse. Efter skabelonen gennemgår jeg sektionerne én for én.

# Projektets navn

Kort 1-linjers beskrivelse af hvad projektet gør.

## Indhold
- [Om projektet](#om-projektet)
- [Demo](#demo)
- [Tech stack](#tech-stack)
- [Kom i gang](#kom-i-gang)
- [Miljøvariabler](#miljøvariabler)
- [Kendte problemer](#kendte-problemer)
- [Roadmap](#roadmap)
- [Bidrag](#bidrag)
- [License](#license)

## Om projektet

Kort beskrivelse af:
- Hvad problemet er
- Hvad din løsning gør
- Hvem du har bygget det til

## Demo

- Live: <link til deploy>
- Video/gif: <link eller billede>

## Screenshots

![Skærmbillede af app](./docs/screenshot-1.png)

## Tech stack

- Frontend: React / Vue / Vanilla JS / osv.
- Backend: Node / Django / Flask / osv.
- Database: Postgres / Mongo / osv.
- Andet: Auth0, Stripe, Tailwind osv.

## Kom i gang

### Forudsætninger

- Node v18+
- npm eller yarn

### Installation

```bash
git clone <repo-url>
cd <mappe-navn>
npm install
```

### Kør lokalt

```bash
npm run dev
```

Applikationen kører nu på http://localhost:5173 (eller det der passer).

## Miljøvariabler

Opret en `.env` fil baseret på `.env.example`:

```env
VITE_API_URL=<din api url>
VITE_AUTH_TOKEN=<din nøgle>
```

## Kendte problemer

- [ ] Responsivt layout på mobil er ikke færdigt
- [ ] Ingen validering på formularer endnu

## Roadmap

- [ ] Tilføj dark mode
- [ ] Skriv enhedstests

## Bidrag

Pull requests er velkomne. For større ændringer, start med et issue.

## License

Distribueret under MIT License. Se `LICENSE` filen for detaljer.

Gennemgang sektion for sektion

Projektbeskrivelse og målgruppe

Det her er svaret på “Hvorfor findes det her repo?”.

Et godt README eksempel på en åbning kunne være:

Et lille værktøj til studerende, der hurtigt vil generere flashcards
ud fra deres forelæsningsnoter i Markdown.

Dårlige versioner er typisk:

• “Skoleprojekt i webudvikling” (siger intet om funktion)
• “Eksperiment” (ja, men med hvad?)

Lav 2-3 bullets om:

• Problemet: “Mange studerende glemmer at repetere forelæsningsnoter.”
• Løsningen: “Appen laver automatisk quiz-questions ud fra Markdown.”
• Målgruppe: “Primært til universitetsstuderende.”

Demo, links og screenshots

Hvis du har et live-link, så sæt det helt i toppen under “Demo”. En rekrutterer klikker ofte der før noget som helst andet.

Eksempel:

- Live: https://flashcards.sarav.dev
- Repo: https://github.com/sarav/flashcards

Hvis du ikke har en deploy, så brug mindst ét screenshot. Læg billeder i en docs/ mappe i repoet, så dine paths er stabile.

Installation og run – så simpelt som muligt

Her taber mange. Installation steps README sektionen må ikke være et tekstafsnit, men rene kopier-bare kommandoer.

Du vil typisk have tre små blokke:

1. Clone + cd
2. Install
3. Kør

Eksempel:

git clone https://github.com/brugernavn/projekt.git
cd projekt
npm install
npm run dev

Skriv også hvad der sker bagefter:

Applikationen er nu tilgængelig på http://localhost:3000
Login med testbruger: test@example.com / kode: test123

Jo mindre din læser skal gætte, jo større sandsynlighed for at de faktisk ser appen køre.

Tech stack og arkitektur (kort)

Det her er mest til folk der kigger fagligt på projektet. Gør det skimme-venligt:

- Frontend: React + Vite
- Styling: Tailwind CSS
- Backend: Express API (Node)
- Database: PostgreSQL via Prisma

Hvis det giver mening, kan du også have et lille arkitektur-afsnit:

Arkitektur (kort):
- SPA frontend der taler med REST API
- JWT-baseret auth
- Docker-compose til lokal udvikling

Hold det til 3-5 bullets. Hvis du vil dykke længere ned, kan du lave en ekstra fil, f.eks. docs/architecture.md, og linke til den.

Miljøvariabler og .env.example

Hvis dit projekt kræver nøgler, tokens eller URLs, så lav altid:

• En sektion i README
• En .env.example fil i repoet

Eksempel på .env.example:

VITE_API_URL=http://localhost:3000/api
VITE_SUPABASE_URL=<din supabase url>
VITE_SUPABASE_KEY=<din public key>

Og så en kort forklaring i README:

Kopiér `.env.example` til `.env` og udfyld dine egne værdier.

Det virker banalt, men manglende .env er en stor grund til “jeg fik det ikke til at køre”.

Kendte problemer og roadmap

Det her er stedet hvor du ærligt kan skrive hvad du godt ved, der mangler.

Jeg plejer at bruge GitHub-style checkboxes, så man kan se det som en lille to do:

## Kendte problemer

- [ ] Ingen validering på loginformular
- [ ] Fejlmeddelelser vises kun i konsollen

## Roadmap

- [ ] Tilføje dark mode
- [ ] Gøre quiz-algoritmen smartere

Det viser at du har overblik, og det hjælper dig selv, når du senere vender tilbage til projektet.

10 typiske README-fejl (og hvordan du retter dem)

1. Ingen installationstrin
   Løsning: Tilføj en “Kom i gang” sektion med 3-5 kommandoer, som kan copy/pastes.
2. Kun teori, ingen demo
   Løsning: Smid et live-link eller mindst ét screenshot ind. En gif er guld.
3. Ingen målgruppe
   Løsning: Skriv eksplicit hvem du har bygget det til: “til undervisere”, “til begyndere i Python” osv.
4. Indvendig viden antages
   F.eks. “kør scriptet som vanligt”. Hvad er “som vanligt”?
   Løsning: Vis hele kommandoen. Hellere én linje for meget end én for lidt.
5. README på dansk, kode på engelsk (eller omvendt)
   Løsning: Vælg et primært sprog. Til portfolio anbefaler jeg engelsk README, men en del danske studieprojekter giver mening på dansk. Vigtigst er konsistens.
6. Ingen info om login/testdata
   Løsning: Tilføj sektion: “Testbrugere” med mail + kodeord, eller forklar hvordan man selv opretter bruger.
7. README matcher ikke længere koden
   Løsning: Når du laver større ændringer (ny build-kommando, ny port, ny database), så opdater README samme dag. Tænk på det som en del af feature-arbejdet.
8. For generisk titel
   Løsning: Ændr “Webudvikling eksamensprojekt” til noget meningsfuldt: “TimeTracker – simpel tidsregistrering for freelancere”.
9. Ingen struktur
   Løsning: Brug en fast struktur som skabelonen ovenfor med sektioner og indholdsfortegnelse.
10. README er bare et dump af opgaveformuleringen
    Løsning: Opgavetekst er ikke en brugsvejledning. Skriv README som om en fremmed skal bruge projektet, ikke som dokumentation til din underviser.

Hvis du vil træne blikket, kan du prøve at åbne et par random repos på GitHub og lave din egen lille “README review”. Hvad savner du, hvis du skulle køre projektet selv?

Bonus: hvornår du bør tilføje CONTRIBUTING og LICENSE

CONTRIBUTING.md

Hvis du bare har et lille studieprojekt, behøver du ikke et langt contributing-dokument.

Men hvis:

• du deler repoet med andre studerende
• du faktisk gerne vil have issues og pull requests

så er en kort CONTRIBUTING.md en god idé.

Eksempel på simpel struktur:

# Bidrag

1. Fork repoet
2. Opret en branch: `git checkout -b feature/min-feature`
3. Commit: `git commit -m 'Tilføj min feature'`
4. Push: `git push origin feature/min-feature`
5. Opret en Pull Request

Du kan også beskrive kode-stil, brug af npm run lint osv. Se f.eks. hvordan open source projekter strukturerer det, eller kig på dokumentation hos GitHub.

LICENSE

Hvis du lægger noget på GitHub uden licensfil, er udgangspunktet faktisk at andre ikke må bruge det frit. Det overrasker mange.

Til studie- og hobbyprojekter vælger mange MIT-licensen, fordi den er meget åben og simpel. Du kan læse mere på choosealicense.com.

Det praktiske:

• Lav en fil der hedder LICENSE i rodmappen
• Indsæt tekst fra den licens du har valgt
• Reference den i README (som i skabelonen)

Sådan kan du bruge det her på 30 minutter

Hvis du vil have effekt hurtigt, så vælg 1-2 af dine vigtigste repos på GitHub. Åbn README, sammenlign med skabelonen her og:

• Tilføj “Kom i gang” blokken med kopier-bare kommandoer
• Smid mindst ét screenshot eller et link til en deploy ind
• Lav en kort “Om projektet” sektion med problem, løsning og målgruppe

Hvis du vil gå videre, kan du også kigge forbi andre indlæg på Coding Class om f.eks. Git og GitHub eller om hvordan du bygger små portfolio-projekter.

Det vigtigste råd: skriv din README til en træt fremmed udvikler der kloner dit repo kl. 23 – og gør det så let som muligt for dem at få projektet til at køre.