Informazioni su wiki, READMEs e Markdown

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

È possibile supportare il team e i collaboratori del progetto usando Markdown per aggiungere formattazione, tabelle e immagini avanzate al progetto team. Il formato Markdown migliora le pagine wiki del progetto del team, il contenuto che aggiungi a un dashboard, il file README del progetto del team o altri file README del repository.

Configurare un wiki del progetto

Un wiki del progetto team consente di condividere informazioni sul progetto con altri membri del team. Quando si configura un wiki da zero, un nuovo repository Git archivia i file Markdown (md), le immagini, gli allegati e la sequenza di pagine. Il wiki supporta la modifica collaborativa del contenuto e della struttura.

I collegamenti seguenti descrivono le funzionalità supportate per un wiki del progetto team.

Pubblicare repository Git su un wiki

Molti team documentano il codice usando i file Markdown, che archiviano nel repository insieme al codice. Sebbene Git supporti la manutenzione e la revisione dei file di documentazione del codice usando il processo di richiesta pull standard, questi file possono presentare problemi ai consumer del contenuto.

• L'utente deve 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 del codice 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 la documentazione del codice in modo sincrono con la codebase e di pubblicare e aggiornare la documentazione in modo selettivo in un wiki.

Esistono differenze significative tra la gestione del contenuto in un wiki per un progetto team e le pagine wiki pubblicate da un repository Git. Per informazioni dettagliate, vedere Pubblicare un repository Git in un wiki.

Migliorare il contenuto del progetto con Markdown

Il formato 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 usare Markdown per fornire indicazioni al team nei modi seguenti:

• Wiki del progetto team
• Codice pubblicato come wiki
• Contenuto del dashboard
• Pagina del progetto o pagine di benvenuto
• File README del repository
• Richieste pull (Pull requests)

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

Aggiungere file README di progetto

È 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 informazioni o posizioni specifiche all'interno del progetto.

Prendere in considerazione l'aggiunta delle indicazioni seguenti:

• Focus del progetto
• Prerequisiti
• Configurare l'ambiente
• Suggerimenti per eseguire operazioni all'interno del progetto
• Scopo o uso di file specifici
• Termini e acronimi specifici del progetto
• Indicazioni sul workflow per il commit o il caricamento delle modifiche e l'aggiunta di nuovi rami
• Sponsor o contatti del progetto

Esempi di README

Ecco alcuni esempi di readmes di progetto in GitHub che supportano tutti i destinatari per riferimento e ispirazione:

• ASP.NET Core
• Visual Studio Code
• Nucleo di Chakra