Über Wikis, READMEs und Markdown

  • Artikel

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

Um Ihr Team oder Mitwirkender für Ihr Projekt zu unterstützen, verwenden Sie Markdown, um Ihrem Teamprojekt umfangreiche Formatierungen, Tabellen und Bilder hinzuzufügen. Sie können das Markdown-Format in einem Teamprojektwiki verwenden, Inhalte, die Sie einem Dashboard, ihrer Teamprojekt-README-Datei oder einer anderen README-Repositorydatei hinzufügen.

Wiki

Verwenden Sie Ihr Teamprojekt-Wiki, um Informationen mit anderen Teammitgliedern zu teilen. Wenn Sie ein Wiki von Grund auf neu bereitstellen, speichert ein neues Git-Repository Ihre Markdowndateien, Bilder, Anlagen und Seitensequenzen. Dieses Wiki unterstützt die gemeinsame Bearbeitung von Inhalten und Strukturen.

Veröffentlichen vorhandener Git-Repositorys in einem Wiki

Viele Teams dokumentieren ihren Code mithilfe von Markdown und checken diese Dateien zusammen mit dem Code ein. Git unterstützt zwar die Standard und Überprüfung dieser Dokumentation zusammen mit standardmäßigen Pullanforderungen, doch stellen solche Dateien den Verbrauchern des Inhalts einige Herausforderungen dar.

  • Leser müssen oft viele Dateien und Ordner durchsuchen, um den Inhalt des Interesses zu finden.
  • Inhalt fehlt an Organisation und Struktur. Es gibt keine inhärente Seitenhierarchie, um Leser zu unterstützen.
  • Die Inhaltsversionsverwaltung wird nicht unterstützt.
  • Das Durchsuchen von Inhalten basiert auf der Suche nach den Codes und nicht auf einer suchumgebung, die für die Suche von Inhalten optimiert ist.

Mit dem Veröffentlichungscode als Wiki-Feature können Sie ein oder mehrere Git-Repositorys veröffentlichen, die in Ihrem Teamprojekt in einem Wiki definiert sind. Dieses Feature bietet eine Möglichkeit, Ihre Inhalte zusammen mit Ihrer Codebasis zu Standard und sie selektiv in einem Wiki zu veröffentlichen und zu aktualisieren.

Es gibt erhebliche Unterschiede zwischen der Verwaltung der Inhalte für ein Wiki, das Sie für ein Teamprojekt bereitstellen, gegenüber Wiki-Seiten, die Sie aus einem Git-Repository veröffentlichen. Ausführliche Informationen finden Sie unter Veröffentlichen eines Git-Repositorys in einem Wiki.

Markdown

Markdown erleichtert das Formatieren von Text und das Einschließen von Bildern. Sie können auch Links zu Dokumenten auf Ihren Projektseiten, README-Dateien, Dashboards und Pullanforderungen erstellen. Mithilfe von Markdown können Sie Ihrem Team anleitungen an folgenden Stellen bereitstellen:

Unterstützte Syntax finden Sie unter Verwenden von Markdown in Azure DevOps.

READMEs

Sie können eine README-Datei oder mehrere Dateien für jedes Repository- oder Teamprojekt definieren. Schreiben Sie Ihre README in Markdown anstelle von Nur-Text.

Verwenden Sie INFO-Seiten, um Mitwirkenden Orientierung für die Arbeit in Ihrem Projekt zu vermitteln. Erwägen Sie das Hinzufügen der folgenden Anleitungen:

  • Projektfokus
  • Voraussetzungen
  • Einrichten der Umgebung
  • Tipps zum Erledigen von Aufgaben innerhalb des Projekts
  • Zweck oder Verwendung bestimmter Dateien
  • Projektspezifische Begriffe und Akronyme
  • Workflowanleitung zum Commit oder Hochladen von Änderungen und Hinzufügen von Verzweigungen
  • Projektsponsoren oder Kontakte

Hier sind einige großartige READMEs, die dieses Format verwenden und alle Zielgruppen für Referenz und Inspiration sprechen: