Como contribuir com a documentação do PHP
A comunidade PHP é maravilhosa porque consegue unir muita gente entusiasmada em torno deste projeto, um dos poucos verdadeiramente Open Source e conduzidos pela comunidade de forma orgânica!
Esta forma orgânica de a comunidade se organizar apesar de bonita, não é infalível: nós sempre precisamos de mais e mais pessoas contribuindo para que a máquina continue girando. Neste artigo você vai conhecer um pouco mais sobre como contribuir com a linguagem através de traduções.
Para contribuir com traduções do PHP você precisa ter uma conta no Github e acessar o projeto php/doc-pt_BR. Neste artigo eu te explico tintim por tintim, num passo a passo como proceder para traduzir o manual da linguagem!
Conteúdo do post
Passo a passo de como contribuir com a documentação do PHP
Passo 1 – Crie uma conta no Github
Você possivelmente já tem um perfil no Github, mas não custa nada deixar aqui um guia para quem ainda não tem ou não sabe alterar arquivos no Github.
Nós temos um artigo incrível sobre como começar com e subir arquivos no Github, bem explicadinho que é pra não ter erro!
Passo 2 – Faça uma cópia do projeto php/doc-pt_BR
Com sua conta criada, é possível fazer uma cópia do repositório php/doc-pt_BR para sua conta pessoal. Desta forma você tem liberdade total para alterar os arquivos a forma como quiser e mais tarde poderá solicitar que suas mudanças sejam integradas à documentação oficial.
Na tela do Github, basta clicar no botão Fork e seguir as instruções:
Fork do Github.Após fazer a cópia (Fork) do projeto, você deverá ter um repositório idêntico em seu perfil do Github. O meu ficou assim:
nawarian/doc-pt_BR.Passo 3 – Escolha com qual arquivo quer trabalhar
Caso você não queira procurar arquivos desatualizados ou mesmo não traduzidos e queira apenas achar uma forma rápida de contribuir, você pode verificar as Issues abertas do projeto. Você provavelmente encontrará alguém que já está coordenando a tradução de uma parte do manual.
Hoje, por exemplo, eu encontrei a Issue #150 que atualiza o arquivo language/namespaces.xml, referente à página do manual Namespaces. Este arquivo possui várias seções e o autor @alfsb está coordenando a tradução de cada uma das partes.
Antes de começar a traduzir um arquivo ou parte dele, avise a comunidade através de issues como esta para evitar retrabalho e conflitos.
Note que, como o arquivo está separadinho em diversas seções, pessoas diferentes podem verificar o que está faltando e contribuir mesmo que com um pequeno pedacinho da documentação!
Outra opção é encontrar arquivos desatualizados utilizando a ferramenta revcheck que a própria comunidade disponibiliza online.
Passo 4 – Se familiarize com a estrutura do documento
A documentação do PHP foi redigida utilizando a linguagem xml no formato DocBook.
Ao navegar pelos arquivos você provavelmente vai entender o que cada elemento faz. Mas abaixo eu deixo uma tabelinha que talvez lhe ajude:
| Elemento XML | Descrição |
<chapter> | Descrição do capítulo do manual |
<title> | Título de uma seção ou exemplo |
<para> | Parágrafo de texto |
<example> | Seção de exemplo |
<programlisting> | Exemplo de código, formatado |
<![CDATA[ ... ]]> | Texto puro, sem formatação |
<sect1> ou <sect2> | Seção do documento, como cabeçalhos da página |
Passo 5 – Altere o arquivo em sua cópia
Aqui você pode optar por clonar a cópia do repositório (Fork) em sua máquina local, como descrito em nosso artigo de como subir arquivos para o Github.
Outra opção é fazer a edição diretamente pela interface gráfica do Github. Foi o que eu fiz quando ajudava a traduzir a Issue #150 que traduz o arquivo language/namespaces.xml. Para isto, na minha cópia (Fork) do repositório eu encontrei o arquivo language/namespaces.xml e abri o editor de texto como na imagem abaixo:
Passo 6 – Faça um commit de suas alterações
Ao finalizar suas alterações completa ou parcialmente, você pode salvar seu progresso ao realizar um Commit de seus arquivos.
Pela interface do Github, logo abaixo do editor de código, encontraremos uma caixa de texto com o título Commit changes. A primeira caixa de texto é o título do commit e a caixa logo abaixo te permite oferecer uma descrição mais detalhada.
Passo 7 – Abra um Pull Request
Agora que você já possui as atualizações que gostaria de lançar à documentação oficial, é hora de solicitar que outras pessoas da comunidade revisem seu texto e aprovem ou solicitem modificações. Para isto nós precisamos abrir um Pull Request.
Em sua cópia do repositório (Fork), clique na aba Pull Requests e clique no botão New pull request:
New pull request.Ao apertar o botão New pull request, assumindo que você fez o commit de suas alterações como descrito no passo anterior, uma tela parecida com a seguinte deverá aparecer:
Se estiver tudo certo em sua opinião basta abrir o Pull Request e aguardar a comunidade revisar. Daqui pra frente, você vai interagir com outras pessoas da comunidade que vão lhe indicar quais alterações realizar ou simplesmente aceitar suas contribuições de bom grado!
O pull request que estou usando como exemplo aqui é o de número #188, disponível aqui.
Modalidades de contribuição com a documentação
O projeto php/doc-pt_br te permite contribuir de duas formas fundamentais: atualizando documentos já desatualizados ou traduzir documentos ainda sem tradução. A prioridade é sempre de documentos desatualizados.
Para além disso, você pode monitorar o repositório para ajudar a revisar issues e pull requests, de forma a permitir que outras pessoas tenham suas alterações aceitas mais cedo.
Mais detalhes você encontra na página Situação atual da Wiki do php/doc-pt_br, que descreve exatamente como encontrar estes arquivos e o que fazer.
Motivos para contribuir com a documentação do PHP
Se fazer parte de um projeto grandioso como o PHP não é motivo o suficiente, eu separei alguns motivos que podem te convencer a contribuir, ou talvez convidar mais pessoas a contribuir com o projeto:
Primeiro motivo: devolver à comunidade. O PHP já ajudou milhares de pessoas a mudar de vida direta ou indiretamente. E, na minha opinião, foi um dos maiores motores para o crescimento do que hoje nós conhecemos como Internet. É um projeto que nasceu e cresceu totalmente aberto e gratuito, contribuir com sua tradução é uma forma de retribuir ao esforço empreendido pela comunidade.
Segundo motivo: destacar seu currículo. Eu ouço de diversas pessoas que estão iniciando agora em programação sobre como fazer com que seu currículo ganhe destaque frente a tantas outras pessoas que se candidatam a mesma vaga. Contribuir com projetos abertos é uma forma incrível de ganhar destaque, ainda mais um projeto complexo como o PHP.
Terceiro motivo: aprender mais e mais detalhes sobre a linguagem PHP. Ao traduzir a documentação você se força a ler, interpretar e entender o conteúdo daquele documento. É uma forma muito boa de solidificar seu conhecimento sobre a linguagem e também de descobrir funcionalidades novas que você talvez não conhecesse antes.
Quarto motivo: treinar para a certificação. A certificação PHP da Zend é a única certificação PHP reconhecida no mundo do trabalho hoje em dia, e te exige profundo conhecimento da linguagem. Traduzir a documentação com certeza te ajuda a revisar material e solidificar conhecimento.
Quinto motivo: praticar o inglês. A documentação original é escrita em inglês, língua essencial para pessoas que trabalham com desenvolvimento de software há muito tempo. Ao traduzir a documentação para o Português, você se força a exercitar seu inglês na forma de leitura, gramática e interpretação de texto com um tópico que você provavelmente já possui familiaridade.
Sexto motivo: participar do Hacktoberfest. O hacktoberfest acontece todo mês de Outubro e é organizado pela DigitalOcean. A ideia é influenciar mais pessoas a contribuírem com projetos de código aberto e, como recompensa, a DigitalOcean e empresas parceiras enviam brindes a quem contribui.
Gostaria de adicionar algum motivo aqui? Me dá um toque lá no Twitter: @nawarian.
O impacto causado ao traduzir o manual do PHP para a língua portuguesa
Cerca de 290 milhões de pessoas no mundo inteiro já falam ou falarão Português em breve! De acordo com a Wikipedia, os 10 países a seguir têm Português como sua língua oficial:
- Brasil
- Angola
- Moçambique
- Portugal
- Guiné-Bissau
- Timor-Leste
- Guiné Equatorial
- Macau
- Cabo Verde
- São Tomé e Príncipe
Ao traduzir o manual da linguagem PHP para a língua portuguesa, você cria impacto direto a todos os países acima citados e ainda ajuda pessoas de outros países que queiram praticar e aperfeiçoar seu domínio da língua portuguesa.
Sem contar com nossos hermanos que por muitas vezes não encontram documentação em espanhol e optam por adivinhar o que está escrito em português.
Conclusão
Fica claro que para contribuir com a linguagem PHP você não precisa saber nada sobre a linguagem C. Um pouco de tempo livre, boa vontade e um dicionário já são suficientes pra te colocar em posição de ajudar a comunidade a crescer.
Além disso o impacto causado por uma pequena tradução para o português é multiplicado por 10, visto que tantos países adotam a língua portuguesa como língua oficial. E tantos outros têm a opção de arriscar um portunhol.
Por fim, participar da comunidade e contribuir com projetos Open Source é uma forma sensacional de tornar-se uma profissional melhor, tanto como pessoa quanto tecnicamente.
Comentários