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!

 

 

Etiquetas do documento e colaboradores

Colaboradores desta página: wbamberg, BrunoThomaz
Última atualização por: wbamberg,