Compartilhar via

Sobre wikis, READMEs e Markdown

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

Você pode dar suporte a colaboradores de sua equipe e projeto usando o Markdown para adicionar formatação avançada, tabelas e imagens ao projeto de equipe. O formato Markdown aprimora as páginas wiki do projeto de equipe, o conteúdo que você adiciona a um painel, o arquivo README do projeto de equipe ou outros arquivos README do repositório.

Configurar um wiki do projeto

Um wiki de projeto de equipe permite que você compartilhe informações sobre seu projeto com outros membros da equipe. Quando você configura um wiki do zero, um novo repositório Git armazena seus arquivos markdown (.md), imagens, anexos e sequência de páginas. O wiki dá suporte à edição colaborativa de seu conteúdo e estrutura.

Os links a seguir descrevem os recursos com suporte para um wiki de projeto de equipe.

Criar um novo wiki

Trabalhar com conteúdo wiki

Formatar conteúdo wiki

Publicar repositórios Git em um wiki

Muitas equipes documentam seu código usando arquivos Markdown, que fazem check-in no repositório junto com seu código. Embora o Git dê suporte à manutenção e revisão de arquivos de documentação de código usando o processo de solicitação de pull padrão, esses arquivos podem apresentar desafios aos consumidores do conteúdo.

  • O usuário geralmente deve examinar muitos arquivos e pastas para encontrar o conteúdo de interesse.
  • O conteúdo carece de organização e estrutura. Não há hierarquia de página inerente para oferecer suporte aos leitores.
  • Não há suporte para o controle de versão de conteúdo.
  • A pesquisa por meio do conteúdo depende da pesquisa do código em vez de uma experiência de pesquisa otimizada para pesquisa de conteúdo.

Com o recurso Publicar código como wiki, você pode publicar um ou mais repositórios Git definidos no projeto da sua equipe em um wiki. Esse recurso fornece uma maneira de manter sua documentação de código de forma síncrona com sua base de código e permite que você publique e atualize seletivamente sua documentação para um wiki.

Há diferenças significativas entre como você gerencia o conteúdo em um wiki para um projeto de equipe versus páginas wiki que você publica de um repositório Git. Para obter detalhes, consulte Publicar um repositório Git em um wiki.

Aprimorar o conteúdo do projeto com Markdown

O formato Markdown facilita a formatação de texto e a inclusão de imagens. Você também pode vincular a documentos nas páginas do projeto, arquivos README, painéis e solicitações de pull.

Você pode usar o Markdown para fornecer diretrizes à sua equipe das seguintes maneiras:

Para obter a sintaxe com suporte, consulte Usar Markdown no Azure DevOps.

Adicionar arquivos README do projeto

Você pode definir um arquivo README ou vários arquivos para cada repositório ou projeto de equipe. Escreva seu README em Markdown em vez de texto simples. Use as páginas LEIAME para guiar os contribuidores a informações ou locais específicos em seu projeto.

Considere adicionar as seguintes diretrizes:

  • Foco do projeto
  • Pré-requisitos
  • Configurar o ambiente
  • Dicas para fazer as coisas dentro do projeto
  • Finalidade ou uso de arquivos específicos
  • Termos e acrônimos específicos do projeto
  • Diretrizes de fluxo de trabalho sobre como confirmar ou carregar alterações e adicionar ramificações
  • Patrocinadores ou contatos do projeto

Exemplos de README

Aqui estão alguns exemplos de READMEs de projeto no GitHub que dão suporte a todos os públicos para referência e inspiração: