Contribuindo para o MDN Web Docs
Publicados: 2022-03-10O MDN Web Docs documenta a plataforma web há mais de doze anos e agora é um esforço multiplataforma com contribuições e um Conselho Consultivo com membros do Google, Microsoft e Samsung, bem como representantes do Firefox. Algo que é fundamental para o MDN é que é um grande esforço da comunidade, com a comunidade da web ajudando a criar e manter a documentação. Neste artigo, darei algumas dicas sobre os lugares onde você pode ajudar a contribuir com o MDN e exatamente como fazê-lo.
Se você nunca contribuiu para um projeto de código aberto antes, o MDN é um ótimo lugar para começar. As habilidades necessárias variam de edição de texto, tradução do inglês para outros idiomas, habilidades em HTML e CSS para criar exemplos interativos ou interesse em compatibilidade de navegadores para atualizar dados de compatibilidade de navegadores. O que você não precisa fazer é escrever muito código para contribuir. É muito simples e uma excelente maneira de retribuir à comunidade se você já achou esses documentos úteis.
Contribuindo para as páginas de documentação
O primeiro lugar que você pode querer contribuir é para os próprios documentos do MDN. O MDN é um wiki, então você pode fazer login e começar a ajudar corrigindo ou adicionando a qualquer documentação para CSS, HTML, JavaScript ou qualquer outra parte da plataforma web coberta pelo MDN.
Para começar a editar, você precisa fazer login usando o GitHub. Como é usual em um wiki, todos os editores de uma página são listados e esta seção usará seu nome de usuário do GitHub. Se você observar qualquer uma das páginas em que os contribuidores do MDN estão listados na parte inferior da página, a imagem abaixo mostra os contribuidores atuais da página no CSS Grid Layout.

O que você pode editar?
Coisas que você pode considerar como editor estão corrigindo erros de digitação óbvios e erros gramaticais. Se você for um bom revisor e editor de texto, poderá melhorar a legibilidade dos documentos corrigindo quaisquer erros de ortografia ou outros erros que encontrar.
Você também pode detectar um erro técnico ou em algum lugar onde as especificações foram alteradas e onde uma atualização ou esclarecimento seria útil. Com a enorme variedade de recursos da plataforma da Web cobertos pelo MDN e a taxa de mudança, é muito fácil que as coisas fiquem desatualizadas, se você detectar algo - conserte!
Você pode usar algum conhecimento específico para adicionar informações adicionais. Por exemplo, Eric Bailey vem adicionando seções sobre questões de acessibilidade em muitas páginas. Este é um esforço brilhante para destacar as coisas em que devemos pensar ao usar uma determinada coisa.

Outro lugar que você pode adicionar a uma página é adicionar links “Veja também”. Podem ser links para outras partes do MDN ou para recursos externos. Ao adicionar recursos externos, estes devem ser altamente relevantes para a propriedade, elemento ou técnica que está sendo descrita por esse documento. Um bom candidato seria um tutorial que demonstrasse como usar esse recurso, algo que daria um próximo passo valioso ao leitor em busca de informações.
Como editar um documento?
Assim que estiver logado, você verá um link para Editar nas páginas do MDN, clicando nele, você será direcionado para um editor WYSIWYG para edição de conteúdo. Suas primeiras edições provavelmente serão pequenas alterações; nesse caso, você poderá seguir seu nariz e editar o texto. Se você estiver fazendo edições extensas, vale a pena dar uma olhada no guia de estilo primeiro. Há também um guia para usar o Editor WYSIWYG.
Depois de fazer sua edição, você pode visualizar e publicar. Antes de publicar, é uma boa ideia explicar o que você adicionou e por que usando o campo Comentário de revisão.

Traduções de idiomas
Aqueles de nós com o inglês como primeira língua são incrivelmente afortunados quando se trata de informações na web, sendo capazes de obter praticamente todas as informações que poderíamos desejar em nosso próprio idioma. Se você conseguir traduzir páginas do idioma inglês para outros idiomas, poderá ajudar a traduzir o MDN Web Docs, disponibilizando todas essas informações para mais pessoas.

Se você clicar no ícone de idioma em qualquer página, poderá ver para quais idiomas essas informações foram traduzidas e poderá adicionar suas próprias traduções seguindo as informações da página Traduzindo páginas MDN.
Exemplos interativos
Os exemplos interativos no MDN são os exemplos que você verá no topo de muitas páginas do MDN, como esta para a propriedade grid-area
.

Esses exemplos permitem que os visitantes do MDN testem vários valores para propriedades CSS ou testem uma função JavaScript, ali mesmo no MDN, sem precisar entrar em um ambiente de desenvolvimento para fazer isso. O projeto para adicionar esses exemplos está em andamento há cerca de um ano, você pode ler sobre o projeto e o andamento até o momento no post Trazendo Exemplos Interativos para o MDN.
O conteúdo desses exemplos interativos é mantido no repositório GitHub de exemplos interativos. Por exemplo, se você quisesse localizar o exemplo para grid-area, você o encontraria nesse repositório em live-examples/css-examples/grid
. Sob essa pasta, você encontrará dois arquivos para grid-area
, um arquivo HTML e um arquivo CSS.
grid-area.html
<section class="example-choice-list large" data-property="grid-area"> <div class="example-choice" initial-choice="true"> <pre><code class="language-css">grid-area: a;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: b;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: c;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> <div class="example-choice"> <pre><code class="language-css">grid-area: 2 / 1 / 2 / 4;</code></pre> <button type="button" class="copy hidden" aria-hidden="true"> <span class="visually-hidden">Copy to Clipboard</span> </button> </div> </section> <div class="output large hidden"> <section class="default-example"> <div class="example-container"> <div class="transition-all">Example</div> </div> </section> </div>
grid.area.css

.example-container { background-color: #eee; border: .75em solid; padding: .75em; display: grid; grid-template-columns: 1fr 1fr 1fr; grid-template-rows: repeat(3, minmax(40px, auto)); grid-template-areas: "aaa" "bcc" "bcc"; grid-gap: 10px; width: 200px; } .example-container > div { background-color: rgba(0, 0, 255, 0.2); border: 3px solid blue; } example-element { background-color: rgba(255, 0, 200, 0.2); border: 3px solid rebeccapurple; }
Um exemplo interativo é apenas uma pequena demonstração, que usa algumas classes e IDs padrão para que o framework possa pegar o exemplo e torná-lo interativo, onde os valores podem ser alterados por um visitante da página que deseja ver rapidamente como trabalho. Para adicionar ou editar um exemplo interativo, primeiro bifurque o repositório de exemplos interativos, clone-o em sua máquina e siga as instruções na página Contribuindo para instalar os pacotes necessários do npm e poder compilar e testar exemplos localmente.
Em seguida, crie uma ramificação e edite ou crie seu novo exemplo. Quando estiver satisfeito com isso, envie um Pull Request para o repositório de exemplos interativos para solicitar que seu exemplo seja revisado. Para manter os exemplos consistentes, as revisões são bastante minuciosas, mas devem apontar as alterações que você precisa fazer de maneira clara, para que você possa atualizar seu exemplo e aprová-lo, mesclar e adicionar a uma página MDN.

Com praticamente todo o CSS agora coberto (além dos exemplos de JavaScript), o MDN agora está procurando ajuda para construir os exemplos de HTML. Há instruções sobre como começar em um post no Fórum de Discurso do MDN. Confira essa postagem, pois ela fornece links para um documento do Google que você pode usar para indicar que está trabalhando em um exemplo específico, bem como outras informações úteis.
Os exemplos interativos são incrivelmente úteis para as pessoas que exploram a plataforma da web, portanto, adicionar ao projeto é uma excelente maneira de contribuir. Contribuir com exemplos de CSS ou HTML requer conhecimento de CSS e HTML, além da capacidade de criar uma demonstração clara. Este último ponto é geralmente a parte mais difícil, eu criei muitos exemplos interativos de CSS e gastei mais tempo pensando no melhor exemplo para cada propriedade do que realmente escrevendo o código.
Dados de compatibilidade do navegador
Recentemente, os dados de compatibilidade do navegador listados nas páginas MDN começaram a ser atualizados por meio do Projeto de compatibilidade do navegador. Este projeto está desenvolvendo dados de compatibilidade do navegador no formato JSON, que podem exibir as tabelas de compatibilidade no MDN, mas também podem ser dados úteis para outros fins.


Os dados de compatibilidade do navegador estão no GitHub e, se você encontrar uma página com informações incorretas ou ainda estiver usando as tabelas antigas, poderá enviar uma solicitação pull. O repositório contém informações de contribuição, no entanto, a maneira mais simples de começar é editar um exemplo existente. Recentemente, atualizei as informações para a propriedade CSS shape-outside
. A propriedade já possuía alguns dados no novo formato, mas estavam incompletos e incorretos.
Para editar esses dados, primeiro bifurquei os Dados de Compatibilidade do Navegador para que eu tivesse minha própria bifurcação. Eu então clonei isso para minha máquina e criei uma nova ramificação para fazer minhas alterações.
Depois de ter meu novo branch, encontrei o arquivo JSON para shape-outside
e consegui fazer minhas edições. Eu já tinha uma boa ideia sobre o suporte do navegador para a propriedade; Também usei o exemplo ao vivo na página MDN fora da forma para testar para ver o suporte quando não tinha certeza. Portanto, fazer as edições era um caso de trabalhar no arquivo, verificar os números de versão listados para suporte da propriedade e atualizar aqueles que estavam incorretos.
Como o arquivo está no formato JSON é bem simples de editar em qualquer editor de texto. O arquivo .editorconfig explica as regras de formatação simples para esses documentos. Há também algumas dicas úteis nesta lista de verificação.
Depois de fazer suas edições, você pode confirmar suas alterações, enviar sua ramificação para seu fork e, em seguida, fazer uma solicitação de pull para o repositório de dados de compatibilidade do navegador. É provável que, assim como nos exemplos ao vivo, o revisor tenha algumas alterações para você fazer. No meu PR para os dados do Shapes, tive alguns erros na forma como marquei os dados e precisei fazer algumas alterações nos links. Estes eram simples de fazer, e então meu PR foi fundido.
Iniciar
Você pode começar simplesmente escolhendo algo para adicionar e começar a trabalhar nele em muitos casos. Se você tiver alguma dúvida ou precisar de ajuda com alguma coisa, o fórum do MDN Discourse é um bom lugar para postar. O MDN é o lugar para onde vou para procurar informações, o lugar para onde envio novos desenvolvedores e desenvolvedores experientes, e sua força é o fato de que todos podemos trabalhar para torná-lo melhor.
Se você nunca fez um Pull Request em um projeto antes, é um lugar muito amigável para fazer esse primeiro PR e, como espero ter mostrado, existem maneiras de contribuir que não exigem escrever nenhum código. Uma habilidade muito valiosa para qualquer projeto de documentação é escrever, editar e traduzir, pois essas habilidades podem ajudar a tornar a documentação técnica mais fácil de ler e acessível a mais pessoas ao redor do mundo.