Skriv en användbar README

En README är första steget för den som vill använda eller bidra till ett repository. Den ska svara på vad projektet gör, vilken miljö som krävs, hur det körs och kontrolleras samt var man hittar detaljer. Den ska inte samla alla designbeslut eller hemliga driftsuppgifter.

Bra README-struktur

• Syfte: vad projektet gör och inte gör.
• Krav: runtime, SDK, operativsystem och verktyg.
• Snabbstart: minsta testade väg från utcheckning till fungerande lokalt resultat.
• Validering: hur tester körs och vilket resultat som är godkänt.
• Struktur: kort karta över viktiga mappar.
• Bidrag: grennamn, granskning och CI-länkar.
• Begränsningar: ofärdigt arbete, kompatibilitet och felrapportering.

Kommandon måste vara säkra

För känsliga åtgärder behöver du beskriva målmiljö och förutsättningar först. Använd platshållare för adresser och ID:n, men förklara hur de ersätts. Börja inte felsökning med destruktiva kommandon.

Håll roten överskådlig

En kort README kan länka till arkitektur och versionsanteckningar. För HCSTech Docs ligger historiska releasefiler under update-info/, medan rotens README fungerar som startsida för utvecklare.

Övning: Be en utvecklare som inte känner projektet följa README utan hjälp. Anteckna alla ställen där personen måste gissa. Förtydliga dem innan dokumentet byggs ut.

Fortsätt med Git och samarbete och tydliga förklaringar.