Como criar o relatório do projeto

Fase atual:
a temporada de documentos de 2020 terminou em 15 de março de 2021. Consulte a linha do tempo.

Esta página contém diretrizes para redatores técnicos sobre como criar seu relatório de projeto quando você terminar seu trabalho para a temporada deste ano do Documentos.

Como enviar o relatório do projeto

Quando a fase de finalização do projeto for aberta, você poderá enviar o relatório preenchendo um formulário disponível na seção de finalização do projeto no guia de redação técnica.

Informações a serem incluídas no relatório do projeto

Nesta seção, descrevemos o tipo de informação que você pode fornecer no relatório do projeto. O formulário do relatório do projeto incluirá campos de texto livre e perguntas de múltipla escolha.

Forneça um link que direcione para uma descrição do trabalho que você fez.

O link precisa direcionar para um documento que contenha uma breve descrição do trabalho realizado, a documentação que o projeto de código aberto foi mesclado ao repositório, um resumo do estado atual do projeto e uma lista de desafios e aprendizados.

O link será exibido nos resultados da temporada de Documentos publicados no site. Os resultados publicados demonstram o trabalho que você concluiu durante o programa. Os resultados publicados também são uma ótima maneira de você consultar seu trabalho como parte do currículo.

Compartilhe o link com seu mentor e peça uma revisão antes de enviar o relatório do projeto.

Requisitos para o relatório do projeto

Considere os seguintes requisitos:

  • O conteúdo vinculado precisa facilitar a identificação do trabalho que você concluiu durante a temporada de Documentos, ou seja, as mudanças feitas ou a nova documentação que você escreveu.
  • O trabalho precisa estar em um local estável. Não é possível alterar o URL após o envio.
  • Outra pessoa deve ser capaz de usar o conteúdo no (ou referenciado) no destino do link para desenvolver seu trabalho.

    • Se o seu trabalho estiver 100% concluído, outras pessoas devem ser capazes de usá-lo.
    • Se o seu trabalho não estiver 100% concluído, deve ficar claro o que falta fazer.

Bons exemplos de como descrever seu trabalho

Você não precisa realizar todas (ou nenhuma) dessas ações, mas há algumas maneiras de atender aos requisitos:

  • Crie uma postagem do blog, uma página da Web ou uma gist pública do GitHub que descreva o trabalho feito e links para as confirmações feitas e os repositórios em que você trabalhou. Se ainda houver trabalho a ser feito no projeto, inclua uma descrição desse trabalho. Você também pode compartilhar destaques ou peças desafiadoras.

    Essa é a melhor opção, porque permite incluir facilmente muitas informações. Isso é bom porque mostra claramente o trabalho que você fez e facilita o uso e a compreensão da sua contribuição por outras pessoas.

  • Se você estiver usando o GitHub e todo o seu trabalho for coberto por uma única solicitação de envio, use esse link.

    • Verifique se a descrição da solicitação de envio está detalhada.
    • Verifique se a descrição indica claramente que o trabalho é para a temporada de documentos.
    • Se a solicitação de envio precisar de mais trabalho após o término da temporada de documentos, verifique se a última temporada de documentos confirma esse fato.
    • Esse método de fornecer um relatório de projeto tem a vantagem de ter o registro de alterações, uma lista de confirmações e os comentários de revisão em um só lugar.
  • Se o repositório do GitHub for de propósito único para a temporada de documentos, adicione um arquivo README contendo os detalhes do seu trabalho.

  • Crie uma pasta pública no Google Drive e inclua todos os patches que você criou.

  • Crie uma planilha pública com o Planilhas Google e liste todas as confirmações.

  • Link para um único problema em um Issue Tracker público que contenha referências claras ao seu trabalho e a outros elementos apropriados. O problema deve acompanhar todo o trabalho que você fez. Verifique se o problema lista todas as confirmações ou se é fácil encontrá-las de outra maneira.

  • Vincule a uma diferença unificada ou de contexto das suas alterações. Inclua um cabeçalho que inclua o nome do seu projeto técnico de escrita e quem você é, para que seja útil para outras pessoas.

Maus exemplos de como descrever seu trabalho

Não faça o seguinte:

  • Vincule a um tarball ou arquivo ZIP contendo o código-fonte do projeto ou o diretório de trabalho.
  • Link para a parte superior do repositório de origem principal do projeto. Por exemplo, se você estiver trabalhando em cpython, este link não será útil: https://github.com/python/cpython.
  • Link para seu clone do repositório de origem do projeto. Isso torna difícil ver quais são as mudanças, porque seu trabalho está misturado com o de outras pessoas.
  • Link para a descrição do seu projeto no site da Temporada de Documentos.

Para os mentores

Ajude o redator técnico a criar um relatório do projeto adequado. É importante fazer isso antes de criar sua própria avaliação do trabalho do redator técnico.

Verifique os seguintes itens:

  • A inscrição precisa atender aos requisitos descritos acima.
  • O envio precisa incluir uma descrição do trabalho realizado, os requisitos atendidos e os motivos das decisões específicas tomadas.

A ideia da Season of Docs não é que os redatores técnicos produzam muita documentação. É importante que o trabalho seja potencialmente útil para a hospedagem do projeto de código aberto.