README

Den första filen man bör läsa i ett projekt. Den förklarar vad projektet är, hur man kommer igång och var man hittar mer.

Kallas även: README.md, readme-fil, läsmig
Kategori: Utvecklingsflöde

Enkel förklaring

En README är projektets välkomstskylt. Namnet betyder läs mig, och det är just det den är till för: den första filen man ska läsa när man kommer till ett nytt projekt.

Där står vad projektet är och gör, hur man kommer igång och var man hittar mer information.

Teknisk förklaring

README-filen ligger överst i ett repository och heter oftast README.md. Ändelsen .md betyder att den är skriven i Markdown, ett enkelt textformat där till exempel # blir en rubrik och **ord** blir fetstil.

Tjänster som Forgejo visar README-filen automatiskt på repots startsida.

En README brukar innehålla:

vad projektet är och gör
hur man installerar och använder det
hur man bidrar
licensen
var mer dokumentation finns

Praktiskt exempel

Kodkollektivet Academys README visas på repots startsida i Forgejo. Den förklarar:

vad Academy är
vilka kommandon som bygger och testar webbplatsen, i en tabell
hur en kurs är uppbyggd, med ett exempel på mappstrukturen
var den längre dokumentationen finns
vilka licenser som gäller för koden och för kursmaterialet

Det som tar mer plats, som arkitekturen och säkerheten, står i egna dokument som README:n länkar till.

När och varför används det?

README-filen är det som både nya medlemmar och besökare läser först, och den besvarar många av deras första frågor.

Rekommendation:

Ge varje repository en README.
Börja med en eller två meningar om vad projektet är.
Visa de vanligaste kommandona.
Hänvisa till annan dokumentation i stället för att skriva allt i README:n.

Vanliga missförstånd

“README är till för datorn.” Nej. Den skrivs för människor. Datorn bryr sig inte om den.
“.md har något med läkare att göra.” Nej. Det betyder Markdown.
“Allt ska stå i README:n.” Nej. En README ska vara en ingång. Längre dokumentation hör hemma i egna filer, och README:n länkar dit.

Relaterade begrepp

Repository (repo)En projektmapp som Git håller ordning på: alla filer i projektet plus hela historiken av sparade versioner.

ADR (Architecture Decision Record)Ett kort dokument som beskriver ett viktigt tekniskt beslut: vad som beslutades, varför och vad det får för följder.