Contribuição para a documentação

Contribuir com a documentação é uma das atividades mais valiosas, pois ajuda os outros a entender a estrutura.

Como Escrever?

A documentação é destinada principalmente às pessoas que são novatas no assunto. Portanto, ela deve atender a vários pontos importantes:

  • Comece com temas simples e gerais. Passar para tópicos mais avançados no final
  • Tente explicar o tópico da maneira mais clara possível. Por exemplo, tente explicar o tópico a um colega primeiro
  • Fornecer apenas informações que o usuário realmente precisa saber para um determinado tópico
  • Certifique-se de que suas informações sejam precisas. Teste cada código
  • Seja conciso – corte o que você escreve pela metade. E depois sinta-se livre para fazê-lo novamente
  • Use o destaque com moderação, desde fontes ousadas até molduras como .[note]
  • Siga a Norma de Codificação no código

Além disso, aprenda a sintaxe. Para uma prévia do artigo durante a redação, você pode usar o editor de prévia.

Mutações de idiomas

O inglês é o idioma principal, portanto, suas mudanças devem ser em inglês. Se o inglês não for o seu forte, use DeepL Tradutor e outros verificarão seu texto.

A tradução para outros idiomas será feita automaticamente após a aprovação e o ajuste fino de sua edição.

Edições triviais

Para contribuir com a documentação, você precisa ter uma conta no GitHub.

A maneira mais fácil de fazer uma pequena mudança na documentação é usar os links no final de cada página:

  • Show on GitHub abre a versão de origem da página no GitHub. Depois basta pressionar o botão E e você pode começar a editar (você deve estar logado no GitHub)
  • Abrir visualização abre um editor onde você pode ver imediatamente a forma visual final

Como o editor de visualização não tem a capacidade de salvar as mudanças diretamente no GitHub, você precisa copiar o texto fonte para a área de transferência (usando o botão Copy to clipboard) e depois colá-lo no editor no GitHub. Abaixo do campo de edição, há um formulário para submissão. Aqui, não se esqueça de resumir e explicar brevemente o motivo de sua edição. Após a submissão, é criado um chamado pull request (PR), que pode ser editado posteriormente.

Maiores edições

É mais apropriado estar familiarizado com o básico de trabalhar com o sistema de controle de versões Git, em vez de depender apenas da interface GitHub. Se você não estiver familiarizado com Git, você pode se referir ao git – o guia simples e considerar o uso de um dos muitos clientes gráficos disponíveis.

Edite a documentação da seguinte maneira:

  1. no GitHub, criar um garfo do repositório nette/docs
  2. clone este repositório em seu computador
  3. então, fazer mudanças no ramo apropriado
  4. verificar se há espaços extras no texto usando a ferramenta Code-Checker
  5. salvar (comprometer) as mudanças
  6. se você estiver satisfeito com as mudanças, empurre-as para GitHub até sua bifurcação
  7. a partir daí, submetê-los ao repositório nette/docs, criando um pull request (PR)

É comum receber comentários com sugestões. Mantenha-se informado sobre as mudanças propostas e incorpore-as. Adicione as mudanças sugeridas como novos compromissos e reenvie-as ao GitHub. Nunca crie um novo pedido de puxar só para modificar um já existente.

Estrutura de documentação

Toda a documentação está localizada no GitHub, no repositório nette/docs. A versão atual está na filial principal, enquanto as versões mais antigas estão localizadas em filiais como doc-3.x, doc-2.x.

O conteúdo de cada ramo é dividido em pastas principais que representam áreas individuais de documentação. Por exemplo, application/ corresponde a https://doc.nette.org/en/application, latte/ corresponde a https://latte.nette.org, etc. Cada uma destas pastas contém subpastas representando as mutações lingüísticas (cs, en, …) e opcionalmente uma subpasta files com imagens que podem ser inseridas nas páginas da documentação.