Een LEESMIJ maken voor uw opslagplaats

  • Artikel

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Uw Git-opslagplaats moet een leesmij-bestand hebben, zodat kijkers weten wat uw code doet en hoe ze aan de slag kunnen gaan. Uw leesmij moet de volgende doelgroepen spreken:

  • Gebruikers die alleen uw code willen uitvoeren.
  • Ontwikkelaars die uw code willen bouwen en testen. Ontwikkelaars zijn ook gebruikers.
  • Inzenders die wijzigingen in uw code willen indienen. Inzenders zijn zowel ontwikkelaars als gebruikers.

Schrijf uw leesmij in Markdown in plaats van tekst zonder opmaak. Markdown maakt het eenvoudig om tekst op te maken, afbeeldingen op te nemen en indien nodig te koppelen aan meer documentatie uit uw leesmij.

Hier volgen enkele geweldige leesbewerkingen die deze indeling gebruiken en alle drie de doelgroepen spreken, ter referentie en inspiratie:

Een inleiding maken

Begin met uw leesmij met een korte uitleg over uw project. Voeg een schermafbeelding of GIF-animatie toe aan uw inleiding als uw project een gebruikersinterface heeft. Als uw code afhankelijk is van een andere toepassing of bibliotheek, moet u deze afhankelijkheden vermelden in de inleiding of direct eronder. Apps en hulpprogramma's die alleen op specifieke platforms worden uitgevoerd, moeten de ondersteunde besturingssysteemversies hebben die in deze sectie van het leesmij-bestand worden vermeld.

Uw gebruikers helpen aan de slag te gaan

Leid gebruikers door uw code op hun eigen systeem in de volgende sectie van uw leesmij te laten werken. Blijf gefocust op de essentiële stappen om aan de slag te gaan met uw code. Maak een koppeling naar de vereiste versies van alle vereiste software, zodat gebruikers ze gemakkelijk kunnen bereiken. Als u complexe installatiestappen hebt, documenteer dan degenen buiten uw leesmij en maak er een koppeling naar.

Geef aan waar u de nieuwste versie van uw code kunt downloaden. Een binair installatieprogramma of instructies voor het gebruik van uw code via verpakkingshulpprogramma's is het beste. Als uw project een bibliotheek of een interface naar een API is, plaatst u een codefragment met basisgebruik en geeft u voorbeelduitvoer weer voor de code in dat fragment.

Bouwstappen bieden voor ontwikkelaars

Gebruik de volgende sectie van uw leesmij om ontwikkelaars te laten zien hoe ze uw code bouwen vanuit een nieuwe kloon van de opslagplaats en eventuele opgenomen tests uitvoeren. Ga als volgt te werk:

  • Geef meer informatie over de hulpprogramma's die nodig zijn om de code te bouwen en de stappen te documenteren om ze te configureren om een schone build te krijgen.
  • Splits dichte of complexe bouwinstructies op in een afzonderlijke pagina in uw documentatie en koppel deze indien nodig.
  • Voer de instructies uit terwijl u ze schrijft om te controleren of de instructies werken voor een nieuwe inzender.

Houd er rekening mee dat de ontwikkelaar die op deze instructies vertrouwt u na enige tijd niet aan een project hebt gewerkt.

Geef de opdrachten op om testcases uit te voeren die bij de broncode worden geleverd nadat de build is geslaagd. Ontwikkelaars leunen op deze testcases om ervoor te zorgen dat ze uw code niet breken wanneer ze wijzigingen aanbrengen. Goede testcases dienen ook als voorbeelden die ontwikkelaars kunnen gebruiken om hun eigen testcases te bouwen bij het toevoegen van nieuwe functionaliteit.

Gebruikers helpen bij te dragen

Met de laatste sectie van uw leesmij kunnen gebruikers en ontwikkelaars betrokken raken bij het melden van problemen en ideeën voorstellen om uw code beter te maken. Gebruikers moeten worden gekoppeld aan kanalen waar ze fouten kunnen openen, functies kunnen aanvragen of hulp kunnen krijgen bij het gebruik van uw code.

Ontwikkelaars moeten weten welke regels ze moeten volgen om wijzigingen bij te dragen, zoals richtlijnen voor coderen/testen en vereisten voor pull-aanvragen. Als u een inzenderovereenkomst nodig hebt om pull-aanvragen te accepteren of een communitycode af te dwingen, moet dit proces worden gekoppeld aan of gedocumenteerd in deze sectie. Geef aan onder welke licentie de code wordt vrijgegeven en maak een koppeling naar de volledige tekst van de licentie.