Dela via

Om wikis, READMEs och Markdown

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Du kan stödja dina team- och projektdeltagare genom att använda Markdown för att lägga till omfattande formatering, tabeller och bilder i ditt teamprojekt. Markdown-formatet förbättrar wiki-sidor för teamprojekt, innehåll som du lägger till på en instrumentpanel, readme-filen för ditt teamprojekt eller andra README-filer för lagringsplatsen.

Konfigurera en projektwiki

Med en wiki för teamprojekt kan du dela information om ditt projekt med andra teammedlemmar. När du konfigurerar en wiki från grunden lagrar en ny Git-lagringsplats dina Markdown-filer (.md), bilder, bifogade filer och sekvenser med sidor. Wikin stöder samarbetsredigering av dess innehåll och struktur.

Följande länkar beskriver de funktioner som stöds för en wiki för ett teamprojekt.

Skapa ny wiki

Arbeta med wiki-innehåll

Formatera wiki-innehåll

Publicera Git-lagringsplatser på en wiki

Många team dokumenterar sin kod med hjälp av Markdown-filer, som de checkar in på lagringsplatsen tillsammans med sin kod. Git stöder underhåll och granskning av koddokumentationsfiler med hjälp av standardprocessen för pull-begäranden, men dessa filer kan innebära utmaningar för användarna av innehållet.

  • Användaren måste ofta söka igenom många filer och mappar för att hitta det intressanta innehållet.
  • Innehållet saknar organisation och struktur. Det finns ingen inbyggd sidhierarki som stöder läsare.
  • Versionshantering av innehåll stöds inte.
  • Sökning via innehåll är beroende av att söka i koden i stället för en sökupplevelse som är optimerad för att söka efter innehåll.

Med funktionen Publicera kod som wiki kan du publicera en eller flera Git-lagringsplatser som definierats i ditt teamprojekt till en wiki. Med den här funktionen kan du underhålla koddokumentationen synkront med din kodbas och selektivt publicera och uppdatera dokumentationen till en wiki.

Det finns betydande skillnader mellan hur du hanterar innehållet i en wiki för ett teamprojekt jämfört med wiki-sidor som du publicerar från en Git-lagringsplats. Mer information finns i Publicera en Git-lagringsplats till en wiki.

Förbättra projektinnehåll med Markdown

Markdown-formatet gör det enkelt att formatera text och inkludera bilder. Du kan också länka till dokument på projektsidor, README-filer, instrumentpaneler och pull-begäranden.

Du kan använda Markdown för att ge vägledning till ditt team på följande sätt:

Syntax som stöds finns i Använda Markdown i Azure DevOps.

Lägga till README-projektfiler

Du kan definiera en README-fil eller flera filer för varje lagringsplats eller teamprojekt. Skriv README i Markdown i stället för oformaterad text. Använd README-sidor för att orientera deltagare till specifik information eller platser i projektet.

Överväg att lägga till följande vägledning:

  • Projektfokus
  • Förutsättningar
  • Konfigurera miljön
  • Tips för att få saker gjorda i projektet
  • Syfte eller användning av specifika filer
  • Projektspecifika termer och förkortningar
  • Arbetsflödesvägledning om att genomföra eller ladda upp ändringar och lägga till grenar
  • Projektsponsorer eller kontakter

README-exempel

Här är några exempel på projekt-READMEs i GitHub som stöder alla målgrupper för referens och inspiration: