Over wiki's, READMEs en Markdown

  • Artikel

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

Als u uw team of inzenders aan uw project wilt ondersteunen, gebruikt u Markdown om opmaak, tabellen en afbeeldingen toe te voegen aan uw teamproject. U kunt de Markdown-indeling gebruiken in een wiki van een teamproject, inhoud die u toevoegt aan een dashboard, het README-bestand van uw teamproject of een ander README-bestand van de opslagplaats.

Wiki

Gebruik de wiki van uw teamproject om informatie te delen met andere teamleden. Wanneer u een volledig nieuwe wiki inricht, worden uw Markdown-bestanden, afbeeldingen, bijlagen en pagina's opgeslagen in een nieuwe Git-opslagplaats. Deze wiki ondersteunt het gezamenlijk bewerken van de inhoud en structuur.

Bestaande Git-opslagplaatsen publiceren naar een wiki

Veel teams documenteren hun code met behulp van Markdown en check deze bestanden samen met de code in. Hoewel Git ondersteuning biedt voor het onderhoud en de beoordeling van dergelijke documentatie, samen met standaard pull-aanvragen, bieden dergelijke bestanden enkele uitdagingen voor consumenten van de inhoud.

  • Lezers moeten vaak door veel bestanden en mappen bladeren om de inhoud van belang te vinden.
  • Inhoud ontbreekt in de organisatie en structuur. Er is geen inherente paginahiërarchie ter ondersteuning van lezers.
  • Versiebeheer van inhoud wordt niet ondersteund.
  • Het doorzoeken van inhoud is afhankelijk van het doorzoeken van de codes in plaats van een zoekervaring die is geoptimaliseerd voor het zoeken naar inhoud.

Met de publicatiecode als wikifunctie kunt u een of meer Git-opslagplaatsen die in uw teamproject zijn gedefinieerd, publiceren naar een wiki. Deze functie biedt een manier om uw inhoud naast uw codebasis te onderhouden en u kunt uw inhoud selectief publiceren en bijwerken naar een wiki.

Er zijn aanzienlijke verschillen tussen hoe u de inhoud voor een wiki beheert die u inricht voor een teamproject versus wikipagina's die u publiceert vanuit een Git-opslagplaats. Zie Een Git-opslagplaats publiceren naar een wiki voor meer informatie.

Markdown

Met Markdown kunt u eenvoudig tekst opmaken en afbeeldingen opnemen. U kunt ook een koppeling maken naar documenten binnen uw projectpagina's, README-bestanden, dashboards en pull-aanvragen. U kunt uw team op de volgende plaatsen richtlijnen geven met behulp van Markdown:

Zie Markdown gebruiken in Azure DevOps voor ondersteunde syntaxis.

LEESMIJ-bestanden

U kunt een README-bestand of meerdere bestanden definiëren voor elke opslagplaats of elk teamproject. Schrijf uw LEESMIJ in Markdown in plaats van tekst zonder opmaak.

Gebruik LEESMIJ-pagina's om inzenders te oriënteren om binnen uw project te werken. Overweeg de volgende richtlijnen toe te voegen:

  • Projectfocus
  • Vereisten
  • Instellen van de omgeving
  • Tips voor het uitvoeren van dingen binnen het project
  • Doel of gebruik van specifieke bestanden
  • Projectspecifieke termen en acroniemen
  • Werkstroomrichtlijnen voor het doorvoeren of uploaden van wijzigingen en het toevoegen van vertakkingen
  • Projectsponsors of contactpersonen

Hier volgen enkele geweldige READMEs die deze indeling gebruiken en voor alle doelgroepen spreken voor referentie en inspiratie: