Informazioni su wiki, READMEs e Markdown

  • Articolo

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

Per supportare il team o i collaboratori al progetto, usare Markdown per aggiungere formattazione, tabelle e immagini avanzate al progetto team. È possibile usare il formato Markdown all'interno di un wiki del progetto team, il contenuto aggiunto a un dashboard, il file README del progetto team o un altro file README del repository.

Wiki

Usare il wiki del progetto team per condividere informazioni con altri membri del team. Quando si effettua il provisioning di un wiki da zero, un nuovo repository Git archivia i file markdown, le immagini, gli allegati e la sequenza delle pagine. Questo wiki supporta la modifica collaborativa del contenuto e della struttura.

Pubblicare repository Git esistenti in un wiki

Molti team documentano il codice usando Markdown e archiviano questi file insieme al codice. Sebbene Git supporti la manutenzione e la revisione di tale documentazione insieme alle richieste pull standard, tali file presentano alcune problematiche per i consumer del contenuto.

  • I lettori devono spesso analizzare molti file e cartelle per trovare il contenuto di interesse.
  • Il contenuto non dispone di organizzazione e struttura. Non esiste una gerarchia di pagine intrinseca per supportare i lettori.
  • Il controllo delle versioni del contenuto non è supportato.
  • La ricerca nel contenuto si basa sulla ricerca dei codici anziché su un'esperienza di ricerca ottimizzata per la ricerca di contenuto.

Con la funzionalità pubblica codice come wiki, è possibile pubblicare uno o più repository Git definiti nel progetto team in un wiki. Questa funzionalità consente di gestire il contenuto insieme alla codebase e di pubblicare e aggiornare in modo selettivo il contenuto in un wiki.

Esistono differenze significative tra il modo in cui si gestisce il contenuto per un wiki di cui si effettua il provisioning per un progetto team rispetto alle pagine wiki pubblicate da un repository Git. Per informazioni dettagliate, vedere Pubblicare un repository Git in un wiki.

Markdown

Markdown semplifica la formattazione del testo e l'inclusione di immagini. È anche possibile collegare documenti all'interno delle pagine del progetto, file README, dashboard e richieste pull. È possibile fornire indicazioni al team nelle posizioni seguenti usando Markdown:

Per la sintassi supportata, vedere Usare Markdown in Azure DevOps.

READMEs

È possibile definire un file README o più file per ogni repository o progetto team. Scrivere il file README in Markdown invece di testo normale.

Usare le pagine README per orientare i collaboratori a lavorare all'interno del progetto. Prendere in considerazione l'aggiunta delle indicazioni seguenti:

  • Stato attivo del progetto
  • Prerequisiti
  • Impostazione dell'ambiente
  • Suggerimenti per eseguire operazioni all'interno del progetto
  • Scopo o uso di file specifici
  • Termini e acronimi specifici del progetto
  • Indicazioni sul flusso di lavoro sul commit o il caricamento di modifiche e l'aggiunta di rami
  • Sponsor o contatti del progetto

Ecco alcuni ottimi READMEs che usano questo formato e parlano a tutti i destinatari per riferimento e ispirazione: