Het moet elk aspect bevatten dat de ontwikkelaar moet weten en dat niet rechtstreeks van de code. Deze bevatten onder andere ontwikkelings-dos en don'ts, volledige implementatie-instructies, beschrijvingen van externe integratie, enzovoort. Deze post leidt je door het maken van een krachtig, mooi en leesbaar README-bestand voor je project.

Een mooie introductie voor goed voorbereide projectdocumentatie is te vinden op github guides: https://guides.github.com/features/wikis/. Dit stelt dat "README alleen de noodzakelijke informatie moet bevatten voor ontwikkelaars om aan de slag te gaan met het gebruik van en bijdragen aan het project".

Met dit in gedachten introduceren we een lijst met onderdelen en best practices die we bij Codest volgen voor het maken van projectdocumentatie.

Snelle introductie

- Titel project: dit is een must-have voor elke README.

- StatusbadgesAls je gebruik maakt van externe code kwaliteitsmetingen, geautomatiseerd testen of andere tools, dan is het begin van het document een goede plek om anderen te laten zien of ze werken.

- BeschrijvingNeem een paar zinnen op over het project om snel het belangrijkste doel te beschrijven en wat het doet.

Inhoudsopgave

Een inhoudsopgave kan nuttig zijn voor lange documentatiebestanden, maar als je README vrij beknopt is, is het niet nodig.

Algemene informatie

- Over sectie: dit zou een meer gedetailleerde beschrijving van het project moeten zijn - het kan informatie bevatten over gebruikers, hun rollen, wat meer verwarrende gevallen, en schermafbeeldingen, enz.

- Mockupseen plaats voor links naar UI/UX mockup-bronnen als die er zijn.

• Andere informatie zoals Toegang tot servers of Integratie met externe API'sVoorbeelden zijn het adres van een staging instance, gedeelde niet-gevoelige (!) toegangsgegevens, links naar documentatie, enkele instructies, enz.

Installatie

- Vereisten: voorwaarden waaraan moet worden voldaan voordat een applicatie wordt geïnstalleerd, bijvoorbeeld de installatie van externe tools.

- Setup: een stap-voor-stap instructie die je kunt volgen om het project op te starten.

- Instellingen: beschrijven waar lokale instellingen worden opgeslagen en geven instructies over hoe u uw eigen instellingen kunt ontvangen.

- Lokale configuratieAls er gevallen zijn voor lokale instellingen, is dit een goede plaats voor uitleg.

Ontwikkeling

Dit gedeelte is een ideale plek voor instructies zoals feature-ontwikkeling, bugfixes, hotfixes, algemene features, testen, stijlgidsen, code-organisatie, andere ontwikkeltools die in het project worden gebruikt (bijv. guards of dockers), enzovoort. Vergeet niet om alle regels te vermelden die elke team lid moet weten.

Inzet

Geef duidelijke stap-voor-stap instructies voor elke omgeving en alles wat "goed om te weten" is tijdens de implementatie.

Andere ideeën voor aparte secties

- API-documentatie

- Changelog

- Externe bronnenEen plaats voor allerlei links die nuttig kunnen zijn.

- Stapel toepassingen: een lijst van de applicatiestack die we in het project gebruiken - kan een korte beschrijving en de naam van de provider bevatten.

Team

Het is discutabel of het nodig is om huidige projectteamleden te tonen (github geeft standaard de volledige lijst van bijdragers), maar het is altijd leuk als je je naam ziet als een van de auteurs van een project. Als je dit doet, houd het dan zo actueel mogelijk.

Een paar laatste woorden

Onthoud: elk project is uniek en dus ook de documentatie. Er is niet één geweldige oplossing voor het schrijven van een README. Volg gewoon de algemene tips, en het belangrijkste is om altijd te denken aan refactoring, wat ook verband houdt met de README. Het is altijd een goed idee om naar het document als geheel te kijken en het te heroverwegen als iets op een andere manier moet worden weergegeven.

Nog één ding: "instructies" zijn belangrijk, dus schrijf ze veel. Bedankt!

Lees meer:

• Open-gesloten principe. Moet ik het ooit gebruiken?
• Hoe schrijf je een goede code?
• Vuekalender. Een nieuw project van Codest gebaseerd op Vue.js