GÅ TILLBAKA
Det sägs att när vi träffar någon för första gången är det första intrycket det viktigaste. Detsamma gäller för ett projekts kodförvar. En välskriven README är avgörande inte bara för nuvarande utvecklare utan även för framtida. Den introducerar projektet och ger steg-för-steg-instruktioner som gör det möjligt att snabbt installera och bidra.
Den ska innehålla alla aspekter som utvecklaren behöver känna till och som inte kan erhållas direkt från kod. Dessa inkluderar utvecklingsåtgärder, fullständiga driftsättningsinstruktioner, beskrivningar av extern integration och så vidare. Det här inlägget kommer att vägleda dig genom att skapa en kraftfull, vacker och läsbar README-fil för din projekt.
En bra introduktion till väl förberedd projektdokumentation finns på github guides: https://guides.github.com/features/wikis/. Där står det att "README ska endast innehålla den information som är nödvändig för att utvecklare ska kunna börja använda och bidra till projektet".
Med detta i åtanke presenterar vi nu en lista över komponenter och bästa praxis som vi på Codest följer för att skapa projektdokumentation.
- Projektets titel: detta är ett måste för varje README.
- StatusbrickorOm du använder externa mätningar av kodkvalitet, automatiserad testning eller andra verktyg är början av dokumentet ett bra ställe att visa andra om de fungerar.
- Beskrivning: inkludera några meningar om projektet för att snabbt beskriva huvudsyftet och vad det gör.
En innehållsförteckning kan vara användbar för långa dokumentationsfiler, men om din README är ganska kortfattad är det inte nödvändigt.
- Om sektionen: detta bör vara en mer detaljerad beskrivning av projektet - den kan innehålla information om användare, deras roller, några mer förvirrande fall och skärmdumpar etc.
- Förlagor: en plats för länkar till UI / UX mockup-resurser om det finns några.
- Krav och önskemål: Förutsättningar som måste uppfyllas innan en applikationsinstallation påbörjas, t.ex. installation av externa verktyg.
- Inställning: en steg-för-steg-instruktion att följa för att komma igång med projektet.
- Inställningar: beskriver var lokala inställningar lagras och ger instruktioner om hur du får dina egna inställningar.
- Lokal konfiguration: om det finns några fall för lokala inställningar är detta en bra plats för en förklaring.
Det här avsnittet är en idealisk plats för instruktioner som funktionsutveckling, buggfixar, hotfixar, gemensamma funktioner, testning, stilguider, kodorganisation, andra utvecklingsverktyg som används i projektet (t.ex. guards eller dockers) och så vidare. Glöm inte att nämna alla de regler som varje Team medlem bör veta.
Ge tydliga steg-för-steg-instruktioner för varje miljö och allt som är "bra att veta" när du gör driftsättningen.
- API-dokumentation
- Changelog
- Externa resurser: en plats för alla typer av länkar som kan vara till hjälp.
- Applikation stack: en lista över den applikationsstack som vi använder i projektet - kan innehålla en kort beskrivning och namnet på leverantören.
Det kan diskuteras om det är nödvändigt att visa aktuella projektgruppsmedlemmar (github tillhandahåller som standard en fullständig lista över bidragsgivare), men det är alltid trevligt om du ser ditt namn som en av författarna till ett projekt. Om du gör detta, håll det så uppdaterat som möjligt.
Kom ihåg: varje projekt är unikt och så är även dess dokumentation. Det finns ingen bra lösning för att skriva en README. Följ bara de allmänna tipsen, och det viktigaste är att alltid komma ihåg refaktorisering, som också är kopplat till README. Det är alltid en bra idé att titta på dokumentet i sin helhet och tänka om om något behöver visas på ett annat sätt.
En sak till: "instruktioner" är nyckeln så skriv dem mycket. Tack så mycket!
Läs mer om detta:
Swedish 
English 
German 
Danish 
Norwegian 
Finnish 
French 
Arabic 
Italian 
Japanese 
Korean 
Polish