Partilhar via

Sobre wikis, READMEs e Markdown

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

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

Configurar um wiki de projeto

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

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

Criar novo wiki

Trabalhar com conteúdo wiki

Formatar conteúdo wiki

Publicar repositórios Git em um wiki

Muitas equipas documentam o seu código usando ficheiros Markdown, que inserem no repositório junto com o seu código. Embora o Git suporte a manutenção e revisão de arquivos de documentação de código usando o processo de solicitação pull padrão, esses arquivos podem apresentar desafios para os consumidores do conteúdo.

  • O usuário muitas vezes deve peneirar 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 do código em vez de uma experiência de pesquisa otimizada para pesquisar conteúdo.

Com o recurso Publicar 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 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 em um wiki.

Há diferenças significativas entre a forma como você gerencia o conteúdo em um wiki 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.

Melhore 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 dentro de suas páginas de projeto, arquivos LEIA-ME, painéis e pull requests.

Você pode usar o Markdown para fornecer orientação à sua equipe das seguintes maneiras:

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

Adicionar arquivos LEIA-ME do projeto

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. Use páginas LEIA-ME para orientar os colaboradores para informações ou locais específicos dentro do seu projeto.

Considere adicionar as seguintes orientações:

  • Foco do projeto
  • Pré-requisitos
  • Configurar o 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

Exemplos do LEIA-ME

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