Om wikis, READMEs och Markdown

  • Artikel

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

Om du vill stödja ditt team eller deltagare i projektet använder du Markdown för att lägga till omfattande formatering, tabeller och bilder i ditt teamprojekt. Du kan använda Markdown-format i en gruppprojekt-wiki, innehåll som du lägger till på en instrumentpanel, din README-fil för gruppprojektet eller en annan README-fil för lagringsplatsen.

Wiki

Använd wiki för ditt teamprojekt för att dela information med andra teammedlemmar. När du etablerar en wiki från grunden lagras dina Markdown-filer, bilder, bifogade filer och sidsekvenser i en ny Git-lagringsplats. Den här wikin stöder samarbetsredigering av innehåll och struktur.

Publicera befintliga Git-lagringsplatser på en wiki

Många team dokumenterar sin kod med Markdown och checkar in de här filerna tillsammans med koden. Även om Git stöder underhåll och granskning av sådan dokumentation tillsammans med vanliga pull-begäranden, utgör sådana filer några utmaningar för användarna av innehållet.

  • Läsare 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 förlitar sig på att söka i koderna i stället för en sökupplevelse som är optimerad för att söka efter innehåll.

Med publiceringskoden som en wiki-funktion kan du publicera en eller flera Git-lagringsplatser som definierats i ditt teamprojekt till en wiki. Den här funktionen är ett sätt att underhålla ditt innehåll tillsammans med din kodbas och gör att du selektivt kan publicera och uppdatera ditt innehåll till en wiki.

Det finns betydande skillnader mellan hur du hanterar innehållet för en wiki som du etablerar 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.

Markdown

Markdown 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 ge vägledning till ditt team på följande platser med Markdown:

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

READMEs

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 inom projektarbetet. Ö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

Här är några bra READMEs som använder det här formatet och talar till alla målgrupper för referens och inspiration: