Como contribuir para a documentação

Contribuir para a documentação é uma das atividades mais gratificantes, pois você ajuda outros a entender o framework.

Como escrever?

A documentação é destinada principalmente a pessoas que estão se familiarizando com o tópico. Portanto, deve atender a vários pontos importantes:

Comece do simples e geral. Passe para tópicos mais avançados apenas no final.
Tente explicar o assunto da melhor maneira possível. Tente, por exemplo, explicar o tópico primeiro a um colega.
Forneça apenas as informações que o usuário realmente precisa saber sobre o tópico em questão.
Verifique se suas informações são realmente verdadeiras. Teste cada código.
Seja conciso – reduza o que você escreve pela metade. E depois, se necessário, novamente.
Economize em todos os tipos de destaque, desde negrito até caixas como .[note].
No código, siga o Padrão de Codificação.

Aprenda também a sintaxe. Para visualizar o artigo enquanto o escreve, você pode usar o editor com visualização.

Versões de idioma

O idioma principal é o inglês, portanto, suas alterações devem estar em tcheco e inglês. Se o inglês não for seu forte, use o DeepL Translator e outros revisarão seu texto.

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

Modificações triviais

Para contribuir com a documentação, é essencial ter uma conta no GitHub.

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

Mostrar no GitHub abre a versão fonte da página dada no GitHub. Em seguida, basta pressionar o botão E e você pode começar a editar (é necessário estar logado no GitHub).
Abrir visualização abre o editor, onde você também vê imediatamente a aparência visual resultante.

Como o editor com visualização não tem a opção de salvar alterações diretamente no GitHub, é necessário, após concluir as edições, copiar o texto fonte para a área de transferência (botão Copiar para área de transferência) e depois colá-lo no editor do GitHub. Abaixo do campo de edição há um formulário para envio. Aqui, não se esqueça de resumir brevemente e explicar o motivo de sua modificação. Após o envio, é criado um chamado pull request (PR), que pode ser editado posteriormente.

Modificações maiores

Mais adequado do que usar a interface do GitHub é estar familiarizado com os fundamentos do trabalho com o sistema de controle de versão Git. Se você não domina o trabalho com o Git, pode consultar o guia git – the simple guide e, opcionalmente, usar um dos muitos clientes gráficos.

Edite a documentação desta forma:

No GitHub, crie um fork do repositório nette/docs.
Clone este repositório para o seu computador.
Em seguida, no branch apropriado, faça as alterações.
Verifique se há espaços em branco extras no texto usando a ferramenta Code-Checker.
Salve as alterações (commit).
Se estiver satisfeito com as alterações, envie-as (push) para o GitHub no seu fork.
A partir daí, envie-as para o repositório nette/docs criando um pull request (PR).

É comum receber comentários com sugestões. Acompanhe as alterações propostas e incorpore-as. Adicione as alterações propostas como novos commits e envie novamente para o GitHub. Nunca crie um novo pull request para modificar um pull request existente.

Estrutura da documentação

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

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