Como escrever um artigo para ajudar as pessoas aprender sobre a Web

MDN's √Ārea de aprendizado √© a nossa casa para artigos que introduzem conceitos Web para novos desenvolvedores. Uma vez que seu conte√ļdo √© voltado para iniciantes, este √© um √≥timo lugar para compartilhar seu conhecimento e ajudar visitantes a conhecer a Web. √Č importante ter certeza que novos desenvolvedores podem seguir o conte√ļdo, ent√£o n√≥s damos aten√ß√£o especial para isto.

Este artigo explica como escrever para a  √Ārea de aprendizado.

Como escrever um artigo na √Ārea de aprendizado

Para começar a contribuir com seu conhecimento, simplesmente clique no botão verde e grande, então siga os cinco passos abaixo. Se você está procurando por ideias, por favor dê uma olhada no nosso quadro de time Trello!

Este artigo pode n√£o acabar exatamente no lugar certo, mas pelo menos no MDN. Se voc√™ deseja falar com algu√©m sobre mover ele para o lugar certo, por favor  Contate-nos.

Passo 1: Escreva uma linha-dupla

A primeira frase do seu artigo precisa resumir sobre qual conte√ļdo voc√™ ir√° falar e a segunda deve ser um pouco mais espec√≠fica sobre os itens que voc√™ vai inserir no seu artigo. Por exemplo:

Enquanto que os arquivos HTML cont√©m conte√ļdo estruturado, CSS, outra grande tecnologia Web, faz o conte√ļdo aparecer do jeito que voc√™ quer. Neste artigo n√≥s vamos cobrir como esta tecnologia funciona, e como escrever seu pr√≥prio exemplo b√°sico.

Note como o exemplo explica brevemente que CSS é uma importante tecnologia Web usada para estilizar páginas. Isto é suficiente para o leitor ter uma boa ideia sobre o quê o artigo fala.

Porque os artigos da √Ārea de Aprendizado primeiramente foca em iniciantes, cada artigo deve cobrir um t√≥pico direto, ent√£o n√£o sobrecarregar√° o leitor com muita informa√ß√£o nova. Se voc√™ n√£o resumir o artigo em uma senten√ßa, voc√™ pode estar tentando fazer muito em somente um artigo!

Passo 2: Adicionar uma top box

Ent√£o adicione uma top box para ajudar os leitores com dicas sobre onde eles est√£o no processo de aprendizagem.  Aqui √© um exemplo de top box do "Entendendo URLs e suas estruturas". Voc√™ pode usar este artigo como um modelo quando estiver escrevendo o seu pr√≥prio.

Pré-requisitos: Você primeiro precisa saber Como a Internet funciona, O que é um servidor Web, and Os conceitos por trás dos links na web.
Objetivo: Você vai aprender o que é uma URL e como ela funciona na Web.
Pré-requisitos
O que o leitor, principalmente, precisa saber para seguir este artigo? Quando poss√≠vel, fa√ßa um link de cada pr√©-requisito para outro artigo da √Ārea de Aprendizado cobrindo o conceito (a menos que este seja um artigo b√°sico que n√£o precisa de nenhum conhecimento anterior).
Objetivos
Esta seção explica brevemente o que o leitor vai aprender no curso da leitura. Este é um pouco diferente da linha-um; a linha-um resume o tópico do artigo, enquando a seção objetivos especificamente descreve o que o leitor pode esperar ao terminar de ler todo o artigo.
 

Nota: Para criar esta tabela você pode copiar e colar a tabela do exemplo acima, ou usar a ferramenta do editor do MDN Tabela. Se você escolher usar a ferramenta Tabela, você precisa especificamente adicionar uma classe CSS learn-box adicional a classe padrão standard-table. Para fazer isto, quando você criar ou editar as propriedades da tabela, vá no painel "Avançado" e no campo Classes mudar para "standard-table learn-box".

Passo 3: Escreva uma descrição completa

Próximo: escreva uma longa descrição que forneça uma visão geral do artigo, destacando os conceitos principais. Não esqueça de explicar por quê o leitor deve pegar seu tempo para aprender este tópico e ler seu artigo!

Passo 4: V√° fundo

Quando voc√™ tiver terminado com tudo isso, voc√™ pode finalmente ir fundo no tema. Voc√™ pode estruturar esta parde do seu artigo como voc√™ quiser (Por quanto sinta-se livre para consultar nosso guia de estilo). Esta √© sua chance de brilhar! Entre nos detalhes explicando o tema que voc√™ est√° escrevendo. Forne√ßa links de refer√™ncia para a documenta√ß√£o completa, explique como a tecnologia funciona em detalhe, forne√ßa detalhes da sintaxe e usabilidade, e mais. √Č com voc√™!

Como um guia, aqui s√£o algumas dicas de escrita para iniciantes:

  • Foque somente em um tema. Se voc√™ sentir que precisa cobrir outros temas, isto significa que voc√™ est√° deixando faltar um pr√©-requisito para o artigo, ou voc√™ precisa quebrar seu artigo em mais de um.
  • Use uma linguagem simples. Evite termos t√©cnicos quando puder, ou pelo menos defina eles e link para os termos do gloss√°rio onde for poss√≠vel.
  • Inclua exemplos diretos para fazer o conceito te√≥rico ser compreendido mais facilmente.Muitas pessoas aprendem melhor com exemplos. Ao contr√°rio de textos acad√™micos, n√≥s queremos que o texto seja leg√≠vel para os iniciantes seguir.
  • Esquemas visuais podem fazer o conte√ļdo mais f√°cil de digerir e carregam informa√ß√£o extra, ent√£o fique √† vontade para usar imagens, diagramas, v√≠deos e tabelas. Se voc√™ est√° usando diagramas ou cartas para incluir texto, n√≥s o encorajamos a usar SVG ent√£o nosso time de tradu√ß√£o pode localizar o texto.

D√™ uma olhada nas primeiras se√ß√Ķes do nosso artigo Fun√ß√Ķes - blocos reutiliz√°veis de c√≥digo para uma boa se√ß√£o descritiva.

Passo 5: Forneça material de "aprendizado ativo"

Para ilustrar o artigo e ajudar o leitor a entender melhor o que ele está aprendendo, esteja certo de fornecer exercícios, tutoriais e tarefas para completar. Tendo eles praticando, e ativamente usando e experimentando os conceitos que seu artigo explica, você pode ajudar a fixar a informação no cérebro do leitor.

Voc√™ pode escolher incluir os exemplos diretamente nas p√°ginas como  exemplos ao vivo, ou fazer links para eles se eles n√£o funciona como exemplos ao vivo. Se voc√™ est√° interessado em ajudar a criar estes materiais de valores, por favor leia o artigo Criar um exerc√≠cio interativo para ajudar o Aprendendo a Web.

Se você não pode fornecer links para materiais de aprendizado ativo (você não conhece nenhum ou não tem tempo para criar), você deveria adicionar uma tag para o artigo. Assim outros contribuintes podem encontrar artigos que precisam de materiais de aprendizado ativo e talvez ajudar você com isto.

Dê uma olhada no Aprendizado ativo: selecionando diferentes elementos para um exemplo de exercício de aprendizado interativo, ou Aprendizado ativo: Jogando com escopo para um estilo diferente de exercício que permite fazer download de um template no dispositivo do leitor e modificá-lo seguindo os passos fornecidos.

Passo 6: Tenha o artigo revisto e colocado no menu de navega√ß√£o da √Ārea de aprendizado

Depois de ter escrito seu artigo, deixe-nos saber para podermos dar uma olhada, fazer uma revisão e sugerir melhorias. Novamente, veja nossa seção Contato, é a melhor maneira de manter contato.

Outra parte na finaliza√ß√£o do seu artigo √© colocar ele na √°rea principal no menu de navega√ß√£o da √Ārea de Aprendizado. Este menu √© gerado pelo LearnSidebar macro, o qual voc√™ precisa de privil√©gios especiais para editar, ent√£o, novamente, converse com algu√©m do nosso time sobre adicionar isto.

Você deveria pelo menos adicionar isso na sua página - isto é feito adicionando a chamada do macro {{LearnSidebar}} dentro de um parágrafo no topo da sua página

Artigos sugeridos

Então você quer contribuir, mas você não tem certeza sobre o que escrever?

O time da √Ārea de aprendizado mant√©m um quadro Trello com ideias de artigos para escrever. Sinta-se livre para pegar um e come√ßar a trabalhar!