Sobre wikis, READMEs e Markdown
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Para dar suporte à sua equipe ou colaboradores ao seu projeto, use o 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 README do projeto de equipe ou outro arquivo README 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.
Os seguintes recursos são suportados para o wiki do projeto de equipe.
Provisionar ou criar um wiki
Trabalhar com conteúdo wiki
- Adicionar e editar páginas de wiki
- Exibir histórico e reverter de página wiki
- Clonar e atualizar o conteúdo da wiki offline
- Usar atalhos de teclado wiki
- Filtrar ou imprimir conteúdo wiki 1
Observação
O recurso de impressão pode não estar disponível no navegador Firefox.
Formatar conteúdo wiki
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 ofereça suporte à manutenção e revisão dessa documentação junto com solicitações de pull padrão, esses arquivos apresentam alguns desafios para os consumidores do conteúdo.
- Os leitores geralmente precisam 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 oferecer suporte aos leitores.
- Não há suporte para o controle de versão de conteúdo.
- A pesquisa de conteúdo depende da pesquisa dos códigos, em vez de uma experiência de pesquisa otimizada para pesquisar conteúdo.
Com o recurso de publicação de código como 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 como você gerencia o conteúdo de um wiki que você provisiona para um projeto de equipe e 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
O 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 fornecer orientação à sua equipe nos seguintes locais usando o Markdown:
Para obter a sintaxe com suporte, consulte Usar Markdown no Azure DevOps.
READMEs
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 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 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
Aqui estão alguns ótimos READMEs que usam esse formato e falam com todos os públicos para referência e inspiração: