Como escrever artigos para a base de conhecimento

Há um monte de coisas para olhar ao escrever ou editar um artigo. Você vai querer ser completo e conciso; factual e envolvente, tudo ao mesmo tempo. Certamente não é a coisa mais fácil do mundo de se fazer. Aqui estão algumas dicas para te ajudar e tornar as coisas um pouco mais fáceis. Além disso, isto é um wiki e sempre podemos rever alguma coisa, se estiver errado.

Escrever para o público em geral, não-técnico

Queremos que a Ajuda do Firefox possa ser usada por todos os usuários do Firefox. Isto significa que estamos escrevendo para o público em geral, em vez de um muito familiarizado com as técnicas de informática e terminologia. Suponha que a pessoa para quem você está escrevendo não sabe como alterar as preferências ou adicionar um botão de barra de ferramentas sem instruções passo-a-passo. Além disso, devemos assumir que eles não mudaram nenhuma das configurações padrão do sistema operacional ou do Firefox.

Escolha um bom título

O título do artigo, juntamente com o seu resumo são as únicas coisas que o usuário tem para julgar se um artigo vai ou não responder a sua pergunta. Chamamos isso de "Confiança do Usuário" e isso impacta diretamente a taxa de cliques. Mesmo que mostremos o artigo correto no topo da lista de resultados da pesquisa, o usuário precisa fazer a conexão mental entre os termos da pesquisa e os resultados que mostramos para que ele decida visualizar o artigo.

O título do artigo deve tentar descrever sobre o que é o artigo. O importante é que as primeiras palavras sejam tão compreensíveis quanto possível, cheio de palavras-chave que são importantes. Isso permitirá aos usuários entender sobre o que é o artigo. Além disso, um título deve seguir estas orientações:

• Tamanho do Título: O Google exibe até 70 caracteres na pesquisa. O título pode ser mais do que isso, se necessário, mas certifique-se que as palavras-chave importantes estão nos primeiros 70 caracteres.
• Tente variar a maneira de citar artigos. Não use os mesmos verbos ou frases em cada título.
• Tente não usar palavras no gerúndio (palavras que terminam em -ndo como "consultando")
• Não use vírgula no título do artigo, uma vez que impede a criação de um link wiki para esse artigo (bug 749835).
• Certifique-se que não há espaços extras no título do artigo pois isso também impede a criação de links para este artigo.

Lembre-se que a explicação completa não precisa estar no título. Você pode usar o resumo para dar ao usuário informações adicionais sobre o que é o artigo.

Corrija o slug

Quando você cria um título, o SUMO criará automaticamente um slug (a parte final da URL do artigo). O slug tem um limite de 50 caracteres. Espaços são renderizados como traços. O slug deve ser coerente com o título, mas, dada a restrição de espaço mais apertado, não precisa ser o mesmo. Não deixe de conferir o auto-gerador de slug. Às vezes uma palavra é cortada ou termina em um traço. Por favor, corrija isso.

Categorias, produtos e temas

Na maioria das vezes, um artigo pertence à categoria solução de problemas ou à categoria como fazer. Ocasionalmente nós escrevemos artigos "Como contribuir" (como este) ou algo em uma das outras categorias.

Os artigos são também "relevante a" pelo menos um produto. Eles também pertencem a um tema principal e opcionalmente a "sub-tema".

Palavras-chave

O campo de palavras-chave em um artigo pode ser usado para melhorar os resultados da pesquisa no SUMO. Ele deve ser usado somente em situações específicas, como o uso indevido pode realmente prejudicar a pesquisa. Raramente precisamos usar palavras-chave. Para saber mais, consulte Quando e como usar palavras-chave para melhorar a classificação de um artigo na busca

Escrever um bom resumo para pesquisa

O resumo do artigo junto com o título são as únicas coisas que o usuário tem para julgar se um artigo vai responder a sua pergunta ou não. Chamamos isso de "Confiança do Usuário" e isso impacta diretamente as taxas de cliques. Mesmo que o artigo correto esteja no topo da lista de resultados, o usuário precisa fazer uma conexão mental entre o que foi consultado e os resultados apresentados para clicar no artigo.

Um resumo de um artigo deve incluir os temas abordados no artigo. Um artigo de resolução de problemas deve tentar incluir sintomas. Além disso, um resumo deve seguir estas orientações:

• Curto e direto ao ponto. Lembra de anúncios classificados? Escreva assim. Os motores de busca cortam qualquer coisa com mais de 160 caracteres.
• Não use marcação wiki.
• Não use "Este artigo explica" em cada resumo. Varie quando possível. Algumas outras frases a serem consideradas:
  • Nós vamos mostrar
  • Vamos explicar
  • Esta página explica
  • Este artigo descreve
  • Vamos explicitar

Faça a sua escrita envolvente

Ajuda do Firefox é um repositório de informações técnicas sobre o funcionamento do navegador web Firefox. A documentação lista as funções de vários recursos do Firefox, procedimentos e instruções para resolver problemas comuns. A documentação pode ser acessada usando a função de pesquisa em cada página, ou você pode simplesmente jogar seu computador pela sala onde unicórnios usarão seus poderes do arco-íris para transformá-lo em doces mágicos que, uma vez consumido, fará de você um ninja nível 70 no computador.

Você está acordado agora? Bom.

O parágrafo anterior parecia ser uma leitura chata até aparecerem os unicórnios. Usar o humor e emoção (SUPRESA!) são algumas das técnicas que podemos usar para prender a atenção das pessoas. As técnicas que listamos abaixo tentam segurar chamar a atenção ao recrear a That paragraph sounds like a boring lecture, at least until the unicorns show up. Using humor and emotion (SURPRISE!) are some of the techniques we can use to engage people. These techniques, which I've listed below, all aim to get your brain to pay attention by recreating what this interaction could be if it were happening in person. When we do that, information is easier to understand and remember.

• Estilo de escrita coloquial – Use um estilo ativo informal semelhante à maneira como você fala com alguém pessoalmente.
• Humor e emoção – Usando o humor é muito bom, mas às vezes é difícil ou impossível de traduzir. Emoções como surpresa e "Eu não sabia disso!" (Não sei o que chamar essa emoção) podem ser mais fáceis para incluir.
• Vários estilos de aprendizagem – Assim como na escola, as pessoas aprendem de forma diferente. Além disso, todo mundo se beneficia ao ver o mesmo conteúdo expresso de várias maneiras.
• Repetição – Quando você explica algo de uma maneira diferente, com diferentes meios de comunicação, também é, obviamente, outra boa maneira de ajudar as pessoas a lembrar o que é importante
• Imagens e vídeo – Usando imagens e vídeo junto com o texto para explicar não é apenas melhor é uma maneira fácil de incluir vários estilos de aprendizagem e repetição.
• Atividades – Especialmente em um tutorial, é bom dar às pessoas algo útil para realizar. Uma coisa é ler as instruções e entender o processo, mas muitas vezes é útil fazer para lembrar como se faz.

O Artigo, Como definir a página inicial é um bom exemplo que utiliza essas técnicas.

Escreva uma boa introdução

Em conjunto com o título e a tabela de conteúdos, a introdução é o que as pessoas vão usar para determinar rapidamente se elas estão no lugar certo.

• Para um tutorial ou uma artigo ensinando como fazer: Dê um breve resumo do que será aprendido.
• Para um artigo de referência: Dê uma breve explicação sobre o recurso.
• Para um artigo de resolução de problemas: Dê um breve resumo do problema e seus sintomas.

Uma boa introdução geralmente pode servir como um bom resumo de pesquisa. Muitas vezes, você pode simplesmente copiá-lo para o campo "Resumo do resultado da pesquisa".

Organize o artigo de forma eficaz

A idéia geral aqui é tentar construir habilidades do simples ao complexo, enquanto tenta manter as informações necessárias para a maioria das pessoas perto da parte superior. Assim, uma solução simples e comum, vêm antes de uma solução complexa.

Use títulos descritivos

Nossos artigos são geralmente abrangentes por isso é importante usar títulos descritivos para ajudar as pessoas a encontrar a parte do artigo que eles precisam. Dê uma olhada na sua tabela de conteúdos. Ela funciona com a introdução, dando uma visão geral do escopo do artigo?

Faça instruções passo-a-passo fáceis de seguir

A principal coisa a ter em mente ao escrever instruções passo-a-passo é ter cuidado para incluir todas as ações necessárias para completar a tarefa. Se, por exemplo, você tem de clicar em "OK" depois de selecionar uma preferência, a fim de passar para a próxima etapa, não se esqueça de incluir para clicar em OK como parte dessa etapa. Algumas coisas a considerar:

• Há sempre várias maneiras para alcançar o resultado. Devemos sempre escolher a forma mais amigável - usando a interface gráfica do usuário e menus quando possível.
• Use frases completas ao descrever como acessar a interface de usuário.
• Incluir resultados esperados ao dar instruções (por examplo, Clique em OK e a janela se fechará).

Aqui está um exemplo do Artigo Como definir a página inicial com alguma explicação nos parênteses.

Definir um único site como sua página inicial
(O título — O que o passo a passo irá resultar)

Se você gosta de manter as coisas simples, aqui está como configurar sua página inicial em três passos fáceis.
(Contexto - mostra a imagem grande — por que estamos fazendo isso)

1. Abra o site que você quer que seja a sua página inicial.
2. Clique no ícone à esquerda do endereço web, arraste-o para o botão Home.
3. Clique em Sim para defini-la como a sua página inicial.

Experimentar: Clique no botão Home e sua nova página inicial irá carregar na aba atual. Não tem como ficar muito mais fácil do que isso!
(atividade – dar ao leitor uma atribuição e descrever o resultado esperado)

Guia de estilo SUMO

Como falamos anteriormente, você deve usar um estilo de conversação ativa quando escrever. Portanto, você deve evitar dizer coisas como, "Se os favoritos do usuário foram perdidos ..." e, em vez dizer: "Se você perdeu seus favoritos ..." Aqui estão outras questões de estilo comuns que você pode executar em quando escrever artigos de suporte:

Sempre use termos como aparecem na interface do Firefox. por exemplo:

• Plugins não tem hífen.
• Add-ons tem hífen.
• Home page são duas palavras.

Termos gerais de informática:

• A Internet é maiúscula.
• Website é uma palavra.

• Use email em vez de e-mail.
• O plural de CD-ROM é CD-ROMs.

Links para mozilla.org não deve conter o locale:

• Use http://www.mozilla.org/firefox em vez de http://www.mozilla.org/en-US/firefox

Capitalizar os seguintes itens:

• Nomes próprios
• A primeira palavra de uma frase completa
• As letras da abreviações e acrônimos, a menos que eles sejam normalmente minúsculas
• A primeira palavra em listas numeradas ou com marcadores
• O nome de uma tecla no teclado
• A primeira palavra de uma frase completa depois de dois pontos
• A primeira palavra em um cabeçalho ou título

Por uma questão de clareza, não utilize i.e. and e.g.

Temos estilos visuais especiais para uma série de itens que podem ser conseguidos através da adição de marcação wiki adequada ao redor do item (veja Marcações mais usadas para os estilos mais comuns).

Nós temos uma marcação especial no wiki – {for} – que permite que você direcione as informações para versões específicas do Firefox ou para sistemas operacionais específicos. Por exemplo, você exibe um conjunto de instruções para as pessoas que executam o Windows e outro para pessoas que usam o Mac OS X (veja Como usar {for} para mais detalhes).