À propos des wikis, readMEs et Markdown

  • Article

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

Pour prendre en charge votre équipe ou vos contributeurs à votre projet, utilisez Markdown pour ajouter une mise en forme enrichie, des tableaux et des images à votre projet d’équipe. Vous pouvez utiliser le format Markdown dans un wiki de projet d’équipe, le contenu que vous ajoutez à un tableau de bord, le fichier README de votre projet d’équipe ou un autre fichier README du dépôt.

Wiki

Utilisez le wiki de votre projet d’équipe pour partager des informations avec d’autres membres de l’équipe. Quand vous provisionnez un wiki à partir de zéro, un nouveau dépôt Git stocke vos fichiers Markdown, images, pièces jointes et séquence de pages. Ce wiki prend en charge la modification collaborative de son contenu et de sa structure.

Les fonctionnalités suivantes sont prises en charge pour le wiki du projet d’équipe.

Provisionner ou créer un wiki

Utiliser du contenu wiki

Remarque

La fonctionnalité d’impression peut ne pas être disponible à partir du navigateur web Firefox.

Mettre en forme le contenu wiki

Publier des référentiels Git existants sur un wiki

De nombreuses équipes documentent leur code à l’aide de Markdown et archivent ces fichiers avec le code. Bien que Git prenne en charge la maintenance et l’examen de cette documentation ainsi que les demandes de tirage standard, ces fichiers présentent quelques défis pour les consommateurs du contenu.

  • Les lecteurs doivent souvent parcourir de nombreux fichiers et dossiers pour trouver le contenu d’intérêt.
  • Le contenu manque d’organisation et de structure. Il n’existe aucune hiérarchie de pages inhérente pour prendre en charge les lecteurs.
  • Le contrôle de version du contenu n’est pas pris en charge.
  • La recherche dans le contenu s’appuie sur la recherche des codes plutôt que sur une expérience de recherche optimisée pour la recherche de contenu.

Avec le code de publication en tant que fonctionnalité wiki, vous pouvez publier un ou plusieurs référentiels Git définis dans votre projet d’équipe sur un wiki. Cette fonctionnalité permet de maintenir votre contenu en même temps que votre base de code et vous permet de publier et de mettre à jour votre contenu de manière sélective sur un wiki.

Il existe des différences significatives entre la façon dont vous gérez le contenu d’un wiki que vous approvisionnez pour un projet d’équipe et les pages wiki que vous publiez à partir d’un dépôt Git. Pour plus d’informations, consultez Publier un dépôt Git sur un wiki.

Markdown

Markdown facilite la mise en forme du texte et l’intégration d’images. Vous pouvez également créer un lien vers des documents dans vos pages de projet, fichiers README, tableaux de bord et demandes de tirage(pull). Vous pouvez fournir des conseils à votre équipe dans les emplacements suivants à l’aide de Markdown :

Pour obtenir la syntaxe prise en charge, consultez Utiliser Markdown dans Azure DevOps.

README

Vous pouvez définir un fichier README ou plusieurs fichiers pour chaque dépôt ou projet d’équipe. Écrivez votre fichier README dans Markdown au lieu de texte brut.

Utilisez des pages README pour orienter les contributeurs afin qu’ils travaillent dans votre projet. Envisagez d’ajouter les instructions suivantes :

  • Focus du projet
  • Prérequis
  • Configuration de l’environnement
  • Conseils pour effectuer des tâches au sein du projet
  • Objectif ou utilisation de fichiers spécifiques
  • Termes et acronymes spécifiques au projet
  • Conseils de flux de travail sur la validation ou le chargement des modifications et l’ajout de branches
  • Commanditaires ou contacts du projet

Voici quelques excellents READMEs qui utilisent ce format et parlent à tous les publics pour référence et inspiration :