README.md

Kennisbank Aan de slag
1

Een README.md bestand dient ervoor om de belangrijkste informatie over een project te verstrekken. Een aantal dingen die in een readme terug zouden moeten komen zijn:

  • Een korte samenvatting: wat doet het project precies en wat is het doel van het project? Waarom is het in het leven geroepen?
  • Een installatie-instructie: hoe kan ik het project installeren?
  • Een gebruiksinstructie: een instructie over hoe je het project kan gebruiken/ aanroepen.
  • Contributing richtlijnen: hoe kan iemand bijdragen aan het project? Met een linkje naar de contributing.md in het project.
  • Licentieinformatie: onder welke licentie is het project uitgebracht en welke consequenties heeft dit voor de mogelijkheden van eventueel gebruik?

Example

Een handige bron bij het maken van een readme is makeareadme.com.

1 like
2

Zie hiervoor ook met name: https://standard.publiccode.net/

3

@jgroenen vraag me af of de Standard for Public Code een goede bron is voor iemand die een README wil maken. Ik vind hier bijvoorbeeld wel iets wat in de README zou moeten staan, namelijk;

Make sure that appropriate communication channels for asking maintainers and stakeholders questions are easy to locate, for instance in the README.

Maar nergens een heldere opsomming van wat ik allemaal op zou moeten nemen.

4

Ha, yes, ik heb geopperd om een NL Profiel op te stellen, met concrete invulling van de diverse punten, zoals ook licentiekeuze bijv. Maar ik zou de Standard sowieso opnemen, en dan in het verlengde daarvan de readme verder specificeren, bijvoorbeeld dus als een NL Profiel voor de Standard.