Como um contribuidor da base de conhecimento, você usa palavras para ajudar meio bilhão de usuários. É um grande trabalho. Usuários chegam à base de conhecimento de todo o mundo e esperam soluções fáceis, mas também queremos encantá-los com nossa voz. Como fazer isso? Aqui estão algumas coisas que descobrimos em nossa pesquisa.

Tom

Escreva com a marca em mente. A Mozilla é sobre a escolha do usuário. Acreditamos na liberdade e flexibilidade. Valorizamos a privacidade e a segurança. Somos uma organização sem fins lucrativos impulsionada pela comunidade, com contribuidores de todo o mundo que compartilham valores comuns.

Você não precisa martelar essa história toda vez que escreve um artigo. É apenas algo para se ter em mente ao descrever recursos.

Estilo de escrita

Escreva para um público geral e não técnico.

Queremos que nossos artigos possam ser usados por todos, não apenas por usuários avançados. Isso significa que estamos escrevendo para um público geral, em vez de um muito familiarizado com técnicas e terminologia de computação. Suponha que a pessoa para quem você está escrevendo não sabe como alterar preferências ou adicionar um botão na barra de ferramentas sem instruções passo a passo. Além disso, devemos supor que não foi alterada nenhuma configuração padrão do aplicativo ou do sistema operacional.

Para resumir, você deve seguir estas diretrizes:

1. Seja breve. As pessoas vêm à base de conhecimento em busca de soluções rápidas. Elas podem não se importar com o funcionamento interno da ferramenta – elas só querem saber o que elas devem fazer para consertar. Vá em frente e corte algumas palavras. Veja o quanto você pode transmitir com menos palavras. É como poesia!
2. Seja claro. Evite jargões. Seja específico. Use palavras no título e no artigo que o leitor usaria. Se seu sobrinho de 13 anos não entender, escreva de forma que ele entenda. Veja a próxima seção para um guia mais extenso.
3. Seja amigável, divertido e empático. (Em resumo: seja humano.) Ok, os usuários não vêm ao suporte esperando diversão. É isso que torna isso poderoso. Ilumine o dia do usuário com um pouco de humor. Mas tenha cuidado para não sacrificar a clareza usando metáforas ou expressões divertidas. Se você não tiver certeza de como equilibrar isso, apenas escreva instruções diretas e use o tom na introdução ou na conclusão.
4. Conte uma história. Tenha um começo, um meio e um fim. Mas não escreva um romance (veja a diretriz nº 1).
   • Começo: isso dá ao leitor algum contexto. Sobre o que é este artigo e por que devo me importar? Seja breve.
   • Meio: As instruções vão aqui. Isso deve responder a “Como eu faço isso?”
   • Fim: Existem próximos passos para o artigo ou recurso? Diga ao leitor para onde ele ou ela deve ir em seguida se quiser saber mais.

Leia a próxima seção para diretrizes mais abrangentes.

Estilo de escrita (abrangente)

• Estilo de escrita coloquial – Use um estilo informal e ativo, semelhante à maneira como você falaria com alguém pessoalmente.
• Humor e emoção – Usar humor é ótimo, mas às vezes é difícil ou impossível de localizar. Emoções como surpresa e “Eu não sabia disso/Eureka!” podem ser mais fáceis de incluir.
• Múltiplos estilos de aprendizado – Assim como na escola, as pessoas aprendem de maneiras diferentes. Além disso, todos se beneficiam ao ver o mesmo conteúdo expresso de várias maneiras.
• Repetição – Quando você explica algo de uma maneira diferente com mídias diferentes, você também está, obviamente, repetindo, o que é outra boa maneira de ajudar as pessoas a se lembrarem do que é importante.
• Imagens e vídeo – Usar imagens e vídeo junto com texto não é apenas a melhor alternativa para ajudar pessoalmente, é uma maneira fácil de incluir múltiplos estilos de aprendizado e repetição. Muitas imagens, no entanto, podem dificultar a localização de um artigo, então tente adicionar imagens apenas quando for útil para um passo ou conceito. Por exemplo, para um passo que é clicar em um botão, você poderia dizer “Clique em OK” em vez de adicionar uma captura de tela da caixa de diálogo desse botã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 lembrar e permitir que as pessoas experimentem as coisas.

Tipos de artigo

Usar tipos de conteúdo consistentes para nossos artigos da base de conhecimento tem muitos benefícios, incluindo facilidade de navegação e maior clareza e organização, além de nos ajudar a criar conteúdo de forma mais eficaz. Estamos em transição para categorizar os artigos externos da base de conhecimento em quatro tipos, cada um servindo a um propósito específico:

• Sobre: Estes artigos abordam perguntas do tipo “O que é…”, fornecendo informações essenciais para ajudar os leitores a entender um tópico.
• Como fazer: Estes artigos se concentram em responder a perguntas do tipo “Como…?”, guiando os leitores através dos passos necessários para alcançar um objetivo ou procedimento específico.
• Solução de problemas: Estes artigos auxiliam os usuários a identificar, diagnosticar e resolver problemas comuns que possam encontrar com um produto, serviço ou recurso, abordando perguntas do tipo “Como…?” relacionadas à resolução de problemas.
• Perguntas frequentes: Estes artigos contêm respostas concisas para perguntas frequentes sobre um único tópico, que podem não se encaixar em outros artigos individuais da base de conhecimento, fornecendo uma referência rápida para consultas comuns.

Comece com um título eficaz e descritivo

Um título bem elaborado é mais do que apenas um rótulo; é o primeiro ponto de contato de um usuário com seu artigo da base de conhecimento. Um bom título não deve apenas chamar a atenção do leitor, mas também servir como uma prévia concisa e informativa do conteúdo do artigo. Ao criar títulos para o SUMO, considere o seguinte:

• Clareza e descrição: Corresponda ao que o artigo trata e ao que o usuário está procurando. Seja conciso, mas focado no usuário.
• Inclusão de palavras-chave: Incorpore palavras-chave relevantes para melhorar a visibilidade nos mecanismos de busca e ajudar os usuários a encontrar seu artigo.
• Concisão: Mantenha os títulos breves, mas ainda fornecendo informações adequadas. Títulos mais curtos são muitas vezes mais amigáveis ao usuário. Tente manter os títulos em torno de 60 caracteres.
• Orientado à ação: Use verbos de ação quando aplicável para indicar o que os usuários podem fazer para resolver um problema ou alcançar um objetivo. Evite usar gerúndios (palavras terminadas em “ndo”) nos títulos para garantir que permaneçam orientados à ação. Evite usar títulos contendo “Como…”.

Escreva uma boa introdução

Junto com o título e o sumário, a introdução é o que ajudará o usuário a determinar se está no lugar certo.

• Para um artigo do tipo “Sobre”: Forneça uma visão geral textual ou definição do conceito e foque em por que o usuário deve se importar com ele.
• Para um artigo do tipo “Como fazer”: Forneça uma visão geral textual ou definição da tarefa e foque na importância ou nos benefícios da tarefa.
• Para um artigo de “Solução de problemas”: Descreva o problema específico ou os sintomas que os usuários podem encontrar. Escreva em linguagem clara e concisa, evitando jargões técnicos sempre que possível.

Tenha em mente que uma boa introdução geralmente pode servir como um bom resumo de pesquisa. Muitas vezes, você pode simplesmente copiá-la para o campo “Resumo do resultado da pesquisa” e pronto.

Organize o artigo de forma eficaz

A ideia 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 vem antes de uma solução complexa.

Faça com que as instruções passo a passo sejam fáceis de seguir

A principal coisa a ter em mente ao escrever instruções passo a passo é ter o cuidado de incluir todas as ações necessárias para concluir a tarefa. Se, por exemplo, você tiver que clicar em OK após selecionar uma preferência para passar para o próximo passo, certifique-se de incluir o clique em “OK” como parte desse passo. Algumas coisas adicionais a considerar:

• Sempre há várias maneiras de alcançar um resultado. Devemos sempre escolher a maneira mais amigável, usando a interface gráfica do usuário e os menus quando possível.
• Use frases completas ao descrever como acessar a interface do usuário.
• Inclua os resultados esperados ao dar instruções (por exemplo, Clique em “OK” e a janela se fechará.).

Legibilidade

O texto deve ser legível. Para isso, você deve:

• Dividir um artigo em pequenos blocos lógicos/semânticos com subtítulos.
• Usar listas numeradas ou com marcadores.
• Escrever frases curtas ou relativamente curtas.
• Evitar escrever parágrafos grandes.

Não há limite para a quantidade de texto. Quanto mais material, melhor; no entanto, você não deve expandi-lo artificialmente. Forneça apenas informações úteis, valiosas e necessárias.

Como criar links para documentação externa de software de terceiros

Ao criar ou atualizar artigos que envolvem ações em software de terceiros, como sistemas operacionais ou aplicativos externos, é crucial fornecer aos usuários informações precisas e confiáveis. No entanto, incluir passos diretos para este software em nossos artigos pode apresentar desafios:

• Informações rapidamente desatualizadas: Atualizações de software de terceiros podem tornar nossas instruções obsoletas, potencialmente confundindo ou enganando nossos usuários.
• Intensivo em recursos: Monitorar e atualizar continuamente os passos para múltiplas plataformas externas exigiria esforço e recursos significativos, o que pode não ser viável.

Melhores práticas

Para garantir que nossos usuários recebam as informações mais confiáveis e atualizadas sem sobrecarregar nossos recursos, siga estas melhores práticas:

• Link para recursos oficiais: Sempre que as instruções envolverem software de terceiros, encontre a documentação oficial ou artigos de ajuda fornecidos pelo fabricante do software. Crie links para esses recursos em vez de escrever os passos diretamente em nossos artigos.
• Forneça contexto: Explique brevemente por que você está direcionando o usuário para uma página externa (por exemplo: "Para os passos mais recentes e precisos para ajustar as configurações do seu sistema, consulte a página de suporte oficial do [nome do software]").
• Verifique os links periodicamente: Embora nosso objetivo seja reduzir a manutenção de instruções de terceiros, verificar periodicamente se os links externos ainda são válidos ainda é importante. Se você notar que um link se tornou desatualizado ou quebrado, procure um link atualizado para a documentação oficial e envie uma revisão.
• Aviso sobre conteúdo externo: Ao direcionar os usuários para um link externo, deixe claro que eles estarão saindo do SUMO e que não somos responsáveis pelo conteúdo de sites externos. Um simples aviso ou nota pode ser suficiente (por exemplo, "Seguir este link o redirecionará para um site externo que não é operado pela Mozilla.").

Exemplo

Imagine que você está escrevendo um artigo sobre a configuração de um recurso do Firefox que depende da alteração de configurações no nível do sistema em um Mac. Em vez de descrever os passos diretamente no artigo, você pode escrever:

Para os passos mais recentes sobre como ajustar as preferências do sistema no macOS, consulte a documentação de suporte oficial da Apple visitando este guia. Observe que seguir esse link o direcionará para um site externo que não é operado pela Mozilla.

Isso garante que você está seguindo as instruções mais atuais diretamente da fonte.

Diretrizes técnicas

• Para aprender como realmente criar um novo artigo, consulte Crie um novo artigo da Base de conhecimento.
• Para aprender como editar um artigo existente, consulte Editar um artigo da Base de Conhecimento.
• Consulte Como funciona a Base de Conhecimento para uma visão geral de como a Base de Conhecimento funciona.
• Consulte Melhorando a base de conhecimento para uma lista completa da documentação de artigos.

Título

• Comprimento do título: a página de resultados de pesquisa do Google exibirá até 60 caracteres. Seu título pode ser mais longo do que isso, se necessário, mas certifique-se de que suas palavras-chave importantes estejam incluídas nos primeiros 60 caracteres.
• Maiúsculas: A primeira palavra do título deve ser maiúscula, assim como nomes próprios e nomes de marcas, não todas as palavras principais. Use o estilo de “frase”, não de “título”. (O mesmo se aplica aos títulos de cabeçalho. Consulte a seção Guia de estilo e regras de redação abaixo para outras regras sobre o uso de maiúsculas.) Não edite, no entanto, o título de um artigo existente para alterar o uso de maiúsculas, a menos que faça outras alterações no título, pois um redirecionamento não será criado e resultará em links wiki quebrados em artigos que apontam para ele (bug 1969540).
• Não use dois pontos no título do artigo, pois isso impede a criação de um link wiki para esse artigo (bug 749835). Certifique-se também de que não há espaços extras no título do artigo, o que também impedirá que os links wiki funcionem.
• Tente variar a maneira como você nomeia os artigos. Não use as mesmas palavras ou frases em todos os títulos. Por exemplo, não comece sempre os artigos com “Como” e evite usar nomes de tarefas no gerúndio, como “Definindo a página inicial”.
• Lembre-se de que a explicação inteira não precisa estar no título. Você pode usar o resumo para dar ao usuário informações adicionais sobre o que está no artigo.

Slug

Quando você cria um novo artigo e insere um título, o SUMO cria automaticamente um slug (a parte após kb/ no final da URL do artigo). Um revisor pode editar o título de um artigo existente, mas o slug permanece o mesmo, a menos que seja alterado manualmente (isso é intencional). O slug tem um limite de 50 caracteres. Espaços são renderizados como hifens. O slug deve ser consistente com o título, mas, dada a restrição de espaço mais apertada, não precisa ser o mesmo.

Corrija o slug

Certifique-se de verificar o final do slug gerado automaticamente. Às vezes, uma palavra é cortada ou termina com um hífen. Por favor, corrija coisas assim.

Atualize o slug de um artigo existente

Ao atualizar o título de um artigo existente, mantenha o slug atual inalterado, a menos que o novo título represente uma mudança significativa que não se alinhe mais com o slug existente. Manter o slug consistente ajuda a evitar links quebrados e preserva o valor de SEO.

Categorias, produtos e tópicos

Na maioria das vezes, um artigo pertence à categoria Como fazer ou Solução de problemas. Ocasionalmente, escrevemos artigos em uma das outras categorias, como artigos de “Como Contribuir” (como este). A página de Histórico do artigo mostrará a categoria.

Os artigos também são “relevantes para” pelo menos um produto. Eles também pertencem a um “Tópico” principal e, opcionalmente, a um “subtópico”.

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 apenas em circunstâncias específicas, pois o uso indevido pode realmente prejudicar a pesquisa. Raramente precisamos usar palavras-chave. Para detalhes, consulte Quando e como usar palavras-chave para melhorar a classificação de um artigo na busca.

Escreva um bom resumo de pesquisa

O resumo do artigo, juntamente com o título, ajuda os usuários a julgar se um artigo responderá à sua pergunta. Chamamos isso de “Confiança do Usuário” e isso impacta diretamente as taxas de cliques. Mesmo que sirvamos o artigo correto no topo da lista de resultados da pesquisa, o usuário precisa fazer a conexão mental entre a consulta de pesquisa e os resultados que exibimos para que eles cliquem no artigo.

Um resumo para um artigo de como fazer deve incluir os tópicos abordados no artigo. Um artigo de solução de problemas deve tentar incluir os sintomas. Além disso, um resumo deve seguir estas diretrizes:

• Curto e direto ao ponto. Lembra dos classificados? Escreva assim. Os mecanismos de busca podem cortar qualquer coisa com mais de 140 caracteres. Se você usar um resumo mais longo, mantenha as informações importantes no início. Nota: O software da Base de Conhecimento mostrará 20 caracteres restantes quando o resumo atingir 140 caracteres, porque o limite de pesquisa interna é de 160.
• Não use marcação wiki.
• Não use "Este artigo explica" em todos os resumos. Varie quando possível. Algumas outras frases a serem consideradas:
  • Vamos mostrar a você
  • Vamos explicar
  • Esta página explica
  • Este artigo descreve
  • Aprenda como

Número de passos

Ao guiar os usuários por um processo, considere listas ordenadas (listas numeradas). Geralmente, é uma boa prática tentar manter o número total de passos na faixa de seis a sete.

Estrutura paralela

Use a mesma fraseologia ou padrão de palavras para cada passo que você escreve. A estrutura paralela é importante nos artigos da Base de Conhecimento porque torna as coisas claras e fáceis de seguir. Quando elementos semelhantes têm um formato consistente, os usuários podem entender e concluir tarefas com mais tranquilidade. Essa estrutura simplifica as instruções, reduz erros e garante que as informações sejam transmitidas de forma eficaz.

Por exemplo:

1. Encontre Limpar histórico quando o Firefox fechar. Se estiver selecionado:
   1. Clique no botão Settings….
   2. Certifique-se de que Histórico de formulários e pesquisa não está selecionado.
   3. Clique em OK.

Pistas direcionais

Pistas direcionais são referências ou indicadores que guiam os usuários para a localização ou posição específica dentro de uma interface de usuário onde eles precisam realizar uma ação específica. Essas pistas ajudam os usuários a navegar e interagir com software, aplicativos ou sites de forma mais eficaz. Elas geralmente incluem frases como “No canto superior direito”, “No menu do lado esquerdo” ou “Abaixo da barra de pesquisa”, que fornecem aos usuários uma noção clara de onde encontrar e realizar ações.

Nas instruções do seu artigo da Base de Conhecimento, certifique-se de fornecer pistas direcionais antes da ação. Por exemplo, em vez de dizer Clique no botão, use No canto superior direito, clique no botão. Este formato ajuda os usuários a localizar e realizar ações facilmente dentro da interface.

Guia de estilo e regras de redação

Como dissemos antes, você deve usar um estilo ativo e coloquial ao escrever. Evite dizer coisas como “Se os favoritos de um usuário foram perdidos” e, em vez disso, diga “Se você perdeu seus favoritos”. Aqui estão outras questões comuns de estilo e redação que você pode encontrar ao escrever artigos de suporte: Sempre use os termos da maneira como eles aparecem na interface da Mozilla. Por exemplo:

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

Termos gerais de computação:

• Website é uma palavra. Web page (página web) são duas palavras.
• Log in e log out são verbos. Exemplo: “Faça log in no site.” O mesmo se aplica a sign in e sign out. Não use “log into” ou “sign into”.
• Login e logout são substantivos (geralmente usados como adjetivos). Exemplo: “Clique no botão de login.”
• Use email em vez de e-mail.
• O plural de CD-ROM é CD-ROMs.

Links para mozilla.org e firefox.com não devem conter a localidade:

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

Ao incorporar links em frases:

• Evite usar “clique aqui” ou “aqui” como texto do link.
  • Faça: Vá para as configurações da sua conta para cancelar sua assinatura.
  • Não faça: Clique aqui para cancelar sua assinatura.

Use letra maiúscula nos seguintes itens:

• Nomes próprios e nomes, incluindo nomes de marcas, produtos e recursos
• A primeira palavra de uma frase completa
• As letras de abreviações e acrônimos, a menos que 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 após dois pontos
• A primeira palavra em um cabeçalho ou título

Mozilla accounts:

• O “a” em Mozilla accounts é sempre minúsculo, exceto em itens de navegação onde está incluído com outros itens de navegação que usam maiúsculas de título.
• Sempre use “sign in” e “sign out”.
• Na forma verbal, use “sign in to your account” (e não “sign into”) para ser gramaticalmente correto.
• Você também pode usar “Sign in with Mozilla”.
• “Sign” deve ser sempre usado como verbo. Se você estiver usando como substantivo, use “login”.
• Use “sign up” como a chamada para ação para criar uma nova conta.

Para detalhes sobre como se referir a Mozilla accounts em artigos da Base de Conhecimento, consulte Editorial guidelines for Mozilla accounts.

Não use “i.e.” e “e.g.”. Essas abreviações latinas podem confundir as pessoas. Para maior clareza, use “em outras palavras” ou “dito de outra forma” em vez de i.e. quando quiser explicar algo de uma maneira diferente. Use “por exemplo” ou “tal como” em vez de e.g. quando quiser dar exemplos.

Não use vírgulas seriais em uma lista de itens. Por exemplo, use “Extensões, temas e plugins” (sem a vírgula serial), não “Extensões, temas, e plugins”.

Use siglas que são consideradas de entendimento geral. Por exemplo:

• HTTP
• USB
• URL

Números que aparecem na versão de um produto, códigos de erro, teclas e botões não serão escritos por extenso.

Escreva instruções na voz ativa. Escreva instruções na voz ativa. A voz ativa e o tempo presente simplificam as instruções, tornando-as mais fáceis de seguir e incentivando a ação imediata. Exemplo:

“Reinicie o Firefox para atualizar” e não “O Firefox precisa ser reiniciado”.

Escreva por extenso as barras invertidas(\) e as barras normais(/) para caminhos e pesquisas para evitar confusão.

Exemplo: “Alguns nomes de caminho para imagens contêm barras invertidas (\\)”.

Atalhos de teclado Use letra maiúscula na primeira letra de um atalho de teclado ou combinação de atalhos: Ctrl + Shift + C ou Command + Shift + C.

Não use gírias e expressões idiomáticas. Todos os nossos artigos são traduzidos para muitos idiomas diferentes, então são lidos e traduzidos por falantes não nativos de inglês. Gírias e expressões idiomáticas podem ser ambíguas, o que pode confundir os leitores e dificultar a tradução.

Temos estilos visuais especiais para vários itens que podem ser obtidos adicionando a marcação wiki apropriada ao redor do item. Consulte a Marcações mais usadas para os estilos mais comuns.

Temos uma marcação wiki especial – {for} – que permite direcionar informações para versões específicas do Firefox ou sistemas operacionais específicos. Por exemplo, você exibe um conjunto de instruções para pessoas que usam o Windows e outro para pessoas que usam o macOS (consulte Como usar {for} para detalhes).