Partilhar via

Sobre wikis, READMEs e Markdown

  • Artigo

Serviços de DevOps do Azure | Azure DevOps Server 2022 - Azure DevOps Server 2019

Para dar suporte à sua equipe ou colaboradores ao seu projeto, use Markdown para adicionar formatação, tabelas e imagens avançadas ao seu projeto de equipe. Você pode usar o formato Markdown dentro de um wiki de projeto de equipe, conteúdo adicionado a um painel, seu arquivo LEIA-ME de projeto de equipe ou outro arquivo LEIA-ME de repositório.

Wiki

Utilize o wiki do projeto de equipa para partilhar informações com outros membros da equipa. Quando aprovisiona um wiki do zero, um novo repositório Git armazena os ficheiros, as imagens, os anexos e a sequência de páginas Markdown. Este wiki suporta a edição colaborativa do conteúdo e estrutura.

Publicar repositórios Git existentes em um wiki

Muitas equipes documentam seu código usando Markdown e fazem check-in desses arquivos junto com o código. Embora o Git suporte a manutenção e revisão de tal documentação, juntamente com solicitações pull padrão, esses arquivos apresentam alguns desafios para os consumidores do conteúdo.

  • Os leitores muitas vezes devem vasculhar 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 dar suporte aos leitores.
  • O controle de versão de conteúdo não é suportado.
  • A pesquisa de conteúdo depende da pesquisa de códigos, em vez de uma experiência de pesquisa otimizada para pesquisar conteúdo.

Com o código de publicação como um recurso wiki, você pode publicar um ou mais repositórios Git definidos em seu projeto de equipe em um wiki. Esse recurso fornece uma maneira de manter seu conteúdo junto com sua base de código e permite que você publique e atualize seletivamente seu conteúdo em um wiki.

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

Markdown

Markdown facilita a formatação de texto e a inclusão de imagens. Você também pode vincular a documentos dentro de suas páginas de projeto, arquivos LEIA-ME, painéis e solicitações pull. Você pode fornecer orientação à sua equipe nos seguintes locais usando o Markdown:

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

Ficheiros LEIA-ME

Você pode definir um arquivo LEIA-ME ou vários arquivos para cada repositório ou projeto de equipe. Escreva o seu LEIA-ME em Markdown em vez de texto simples.

Utilize as páginas README para orientar os contribuidores para trabalharem no projeto. Considere adicionar as seguintes orientações:

  • Foco do projeto
  • Pré-requisitos
  • Configuração do ambiente
  • Dicas para fazer as coisas dentro do projeto
  • Finalidade ou utilização de ficheiros específicos
  • Termos e acrónimos específicos do projeto
  • Orientação do fluxo de trabalho sobre como confirmar ou carregar alterações e adicionar ramificações
  • Patrocinadores ou contactos do projeto

Aqui estão alguns ótimos READMEs que usam esse formato e falam com todos os públicos para referência e inspiração: