Maak een README
suggesties voor een goede README
elk project is anders, dus overweeg welke van deze secties op het jouwe van toepassing zijn. De secties die gebruikt worden in de template zijn suggesties voor de meeste open source projecten. Houd er ook rekening mee dat hoewel een README te lang en gedetailleerd kan zijn, te lang beter is dan te kort. Als je denkt dat je README te lang is, overweeg dan om een andere vorm van documentatie te gebruiken in plaats van informatie uit te snijden.
naam
Kies een zelfuitleggende naam voor uw project.,
Description
laat mensen weten wat uw project specifiek kan doen. Geef context en voeg een link toe aan alle referentiebezoekers die mogelijk onbekend zijn. Een lijst met functies of een achtergrond subsectie kan hier ook worden toegevoegd. Als er alternatieven zijn voor uw project, is dit een goede plek om onderscheidende factoren op te sommen.
Badges
Op sommige READMEs kunt u kleine afbeeldingen zien die metadata overbrengen, zoals het al dan niet doorgeven van alle tests voor het project. U kunt Shields gebruiken om wat toe te voegen aan uw README. Veel diensten hebben ook instructies voor het toevoegen van een badge.,
Visuals
afhankelijk van wat u maakt, kan het een goed idee zijn om screenshots of zelfs een video op te nemen (u zult vaak GIF ’s zien in plaats van echte video’ s). Tools zoals ttygif kan helpen, maar check out Asciinema voor een meer geavanceerde methode.
installatie
binnen een bepaald ecosysteem kan er een veelgebruikte manier zijn om dingen te installeren, zoals het gebruik van garen, NuGet of Zelfbrew. Echter, overweeg de mogelijkheid dat wie het lezen van uw README is een beginner en zou graag meer begeleiding., Vermelding van specifieke stappen helpt bij het verwijderen van ambiguïteit en krijgt mensen om het gebruik van uw project zo snel mogelijk. Als het alleen draait in een specifieke context zoals een bepaalde versie van een programmeertaal of besturingssysteem of afhankelijkheden heeft die handmatig moeten worden geïnstalleerd, voeg dan ook een subsectie vereisten toe.
gebruik
Gebruik voorbeelden royaal, en Toon de verwachte uitvoer als je kunt. Het is handig om inline het kleinste voorbeeld van gebruik dat u kunt aantonen, terwijl het verstrekken van links naar meer geavanceerde voorbeelden als ze te lang zijn om redelijk op te nemen in de README.,
ondersteuning
vertel mensen waar ze naar toe kunnen gaan voor hulp. Het kan elke combinatie van een issue tracker, een chatroom, een e-mailadres, enz.
Roadmap
als je ideeën hebt voor releases in de toekomst, is het een goed idee om ze in de README op te nemen.
bijdragende
geef aan of u open staat voor bijdragen en wat uw vereisten zijn om ze te accepteren.
voor mensen die wijzigingen aan uw project willen aanbrengen, is het handig om wat documentatie te hebben over hoe u kunt beginnen., Misschien is er een script dat ze moeten uitvoeren of een aantal omgevingsvariabelen die ze moeten instellen. Maak deze stappen expliciet. Deze instructies kunnen ook nuttig zijn voor je toekomstige zelf.
u kunt ook opdrachten documenteren om de code te pluizen of tests uit te voeren. Deze stappen helpen om een hoge kwaliteit van de code te garanderen en de kans dat de veranderingen per ongeluk iets breken te verminderen. Het hebben van instructies voor het uitvoeren van tests is vooral handig als het vereist externe setup, zoals het starten van een Selenium server voor het testen in een browser.,
auteurs en bevestiging
Toon uw waardering voor degenen die hebben bijgedragen aan het project.
Licentie
voor open source projecten, geef aan hoe het gelicentieerd is.
projectstatus
als je geen energie of tijd meer hebt voor je project, plaats dan een notitie bovenaan de README die zegt dat de ontwikkeling is vertraagd of volledig gestopt. Iemand kan ervoor kiezen om uw project te forken of vrijwilliger om in te stappen als een onderhouder of eigenaar, waardoor uw project te blijven gaan. U kunt ook een expliciet verzoek indienen voor onderhouders.