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.
Link para seus trabalhos
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.