Om du någon gång har tittat på ett programmeringsprojekt på GitHub eller varit nyfiken och tittat i program-mappar har du förmodligen stött på en fil som heter README.

Men vad är egentligen en README och varför finns den?

README-filen projektets introduktion och snabbguide. Den ska hjälpa en person som är intresserad av projektet att förstå vad det är, varför det finns och hur man använder eller utvecklar det. README är inte en del av själva programmet, den är en del av dokumentationen.

Vad betyder README?

Namnet kommer från engelskans "read me" – alltså "läs mig". Det är därför README-filen ofta ligger högst upp i ett projekt. På många plattformar, till exempel GitHub, visas den automatiskt på projektets startsida.

Filen heter ofta README.md

.md betyder Markdown, det är ett enkelt textformat som gör det möjligt att använda rubriker, listor, länkar, bilder och annan formatering utan att behöva skriva HTML.

En README kan dock finnas i andra format också. Det viktiga är inte egentligen filändelsen utan att den fungerar som projektets introduktion.

Vad är den bra för?

Tänk dig att du hittar ett programmeringsprojekt som verkar intressant.

Du kanske undrar:

  • Vad gör det här programmet?
  • Varför har någon skapat det?
  • Vem är det tänkt för?
  • Hur installerar jag det?
  • Hur startar jag det?
  • Vilka tekniker används?
  • Finns det något jag behöver veta innan jag börjar?
  • Var hittar jag mer information?

Det är sådana frågor README-filen kan svara på.

En bra README kan göra skillnaden mellan att någon tänker "Det här verkar intressant!" och "Jag förstår inte hur det här fungerar."

Vad brukar finnas i en README?

Det finns ingen exakt mall som alla README-filer måste följa. Innehållet beror på projektet.

Men några delar är väldigt vanliga.

1. Projektets namn

README:n börjar ofta med projektets namn och en kort beskrivning.

Till exempel:

Mitt fantastiska projekt

Ett program för att hålla ordning på familjens gamla fotografier.

Det behöver inte vara mer komplicerat än så.

2. Beskrivning

Här berättar man lite mer om vad projektet faktiskt gör.

Det kan vara bra att svara på tre enkla frågor:

  • Vad är det?
  • Vad kan man göra med det?
  • Vem är det till för?

En kort och tydlig beskrivning är ofta mer användbar än flera sidor teknisk information.

3. Installation

Om projektet behöver installeras brukar README:n beskriva hur.

Det kan till exempel handla om vilka program eller bibliotek som behöver finnas installerade och vilka kommandon som ska köras.

pip install -r requirements.txt

eller:

npm install

Målet är att någon annan ska kunna följa instruktionerna och få projektet att fungera utan att behöva gissa.

4. Så kommer man igång

Efter installationen vill man förstås veta hur programmet startas.

Här kan man visa ett enkelt exempel:

python app.py

eller beskriva hur man öppnar programmet och vad man gör första gången.

För ett bibliotek eller API kan det i stället finnas ett litet kodexempel som visar hur det används.

5. Funktioner

En lista över de viktigaste funktionerna kan ge en snabb överblick.

Till exempel:

  • Skapa och redigera poster
  • Söka efter information
  • Importera data
  • Exportera data
  • Skapa rapporter

Det behöver inte vara en komplett lista över allt programmet kan göra. README:n ska framför allt ge en snabb bild av projektet.

6. Teknik

För programmeringsprojekt är det vanligt att beskriva vilka tekniker som används.

Till exempel:

  • Python
  • Flask
  • Vue
  • SQLite
  • PostgreSQL

Det kan vara användbart både för den som vill använda programmet och för andra utvecklare som funderar på att bidra till projektet.

7. Skärmbilder eller exempel

För program med ett grafiskt gränssnitt kan bilder vara väldigt användbara.

En bild kan ibland förklara mer än flera stycken text.

Det kan också finnas exempel på hur programmet används eller hur resultatet ser ut.

8. Licens

Om projektet är offentligt kan README:n berätta vilken licens som gäller.

Licensen talar bland annat om vad andra får göra med koden.

Exempel på vanliga licenser är MIT, GPL och Apache License.

Det här är särskilt viktigt för open source-projekt, eftersom "koden finns på GitHub" inte automatiskt betyder att andra får göra precis vad de vill med den.

9. Bidrag och utveckling

I större open source-projekt kan README:n också innehålla information om hur andra kan bidra.

Det kan till exempel stå hur man:

  • rapporterar buggar
  • föreslår funktioner
  • skickar in ändringar
  • kör tester
  • bygger projektet lokalt

Ibland finns den här informationen i separata dokument, till exempel CONTRIBUTING.md, för att hålla README:n kortare.

10. Kontakt och mer information

Slutligen kan README:n länka vidare till projektets webbplats, dokumentation, support, issue tracker eller andra relevanta platser.


README:n behöver inte innehålla allt

Det är lätt att tro att en README ska vara en komplett manual för hela programmet. Det behöver den inte vara. README:n fungerar bäst som en väg in i projektet. Den kan ge den viktigaste informationen och sedan hänvisa vidare till mer detaljerad dokumentation.

Ett större projekt kan därför ha exempelvis:

README.md
CONTRIBUTING.md
CHANGELOG.md
LICENSE
docs/

Där varje fil har sitt eget syfte.

  • README berättar vad projektet är och hur man kommer igång.
  • CHANGELOG berättar vad som har förändrats mellan versionerna.
  • CONTRIBUTING berättar hur man kan bidra till projektet.
  • LICENSE berättar vilka rättigheter och villkor som gäller för användning av koden.
  • docs/ kan innehålla mer omfattande dokumentation.


README:n är till för framtida dig också

Det kanske inte alltid är någon annan som behöver förstå projektet.

Ibland är den viktigaste läsaren faktiskt du själv – några månader senare.

När man arbetar med ett projekt är det lätt att tänka:

"Det där kommer jag ihåg."

Sedan går tiden.

Plötsligt sitter man framför sitt eget projekt och undrar:

"Hur var det nu man startade det här?"

En bra README fungerar då som en liten tidskapsel. Den gör det enklare att återvända till ett projekt efter ett uppehåll och förstå hur allt hänger ihop.

Det är en av anledningarna till att dokumentation är en del av själva utvecklingsarbetet, även om den inte körs av programmet.


En enkel tumregel

En README behöver inte vara lång för att vara bra.

För ett litet projekt kan det räcka med:

  • Vad är det?
  • Hur installerar jag det?
  • Hur använder jag det?
  • Var hittar jag mer information?

För ett större projekt behövs kanske betydligt mer.

Det viktigaste är att README:n hjälper nästa person – oavsett om det är en användare, en annan utvecklare eller ditt framtida jag – att snabbt förstå vad projektet är och vad nästa steg är.