Sobre wikis, LEIA-ME e Markdown

  • Artigo

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

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

Wiki

Use o wiki do projeto de equipe para compartilhar informações com outros membros da equipe. Quando você provisiona um wiki do zero, um novo repositório Git armazena seus arquivos, imagens, anexos e sequência de páginas do Markdown. Este wiki dá suporte à edição colaborativa de seu 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.
  • Não há suporte para controle de versão de conteúdo.
  • 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 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 em suas páginas de projeto, arquivos LEIA-ME, painéis e solicitações pull. Você pode fornecer orientação para sua equipe nos seguintes locais usando Markdown:

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

READMEs

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

Use páginas LEIAME para orientar os colaboradores a trabalhar em seu projeto. Considere adicionar as seguintes diretrizes:

  • Foco do projeto
  • Pré-requisitos
  • Configurando o ambiente
  • Dicas para fazer as coisas dentro do projeto
  • Finalidade ou uso de arquivos específicos
  • Termos e siglas específicos do projeto
  • Orientação de fluxo de trabalho sobre como confirmar ou carregar alterações e adicionar ramificações
  • Patrocinadores ou contatos 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: