Como um contribuidor da base de conhecimento, você usa palavras para ajudar quinhentos milhões de utilizadores. É um grande trabalho. Os utilizadores vêm à base de conhecimento de todo o mundo, e esperam soluções fáceis, mas nós também queremos encantá-los com a nossa voz. Como é que faz isso? Aqui estão algumas coisas que descobrimos na nossa pesquisa.

Tom

Escreva com a marca em mente. A `Mozilla` é sobre a escolha do utilizador. Acreditamos na liberdade e flexibilidade. Valorizamos a privacidade e a segurança. Somos uma organização sem fins lucrativos orientada para a comunidade com contribuidores de todo o mundo que partilham valores comuns.

Não precisa de martelar esta história sempre que escreve um artigo. É apenas algo a ter em mente quando está a descrever as funcionalidades.

Estilo de escrita

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

Queremos que os nossos artigos sejam utilizáveis por todos, não apenas por utilizadores avançados. Isto significa que estamos a escrever para um público geral em vez de um que esteja muito familiarizado com as técnicas e terminologia de computadores. Assuma que a pessoa para quem está a escrever não sabe como alterar as preferências ou adicionar um botão à barra de ferramentas sem instruções passo a passo. Além disso, devemos assumir que não alteraram nenhuma das predefinições da aplicação ou do sistema operativo.

Para resumir, deve seguir estas diretrizes:

1. Seja breve. As pessoas vêm à base de conhecimento à procura 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 a corrigir. Vá em frente e corte algumas palavras. Veja o quanto consegue transmitir com menos palavras. É como poesia!
2. Seja claro. Evite o jargão. Seja específico. Use palavras no título e no artigo que o leitor usaria. Se o seu sobrinho de 13 anos não o entender, escreva-o de forma que ele o entenda. Consulte a próxima secção para um guia mais extenso.
3. Seja amigável, divertido e empático. (Em suma: Seja humano.) Ok, os utilizadores não vêm ao suporte à espera de diversão. É isso que torna isto poderoso. Ilumine o dia do utilizador com um pouco de humor. Mas tenha cuidado para não sacrificar a clareza usando metáforas ou expressões divertidas. Se não tiver a certeza de como equilibrar isto, escreva apenas instruções diretas e use o tom na introdução ou na conclusão.
4. Conte uma história. Tenha um início, um meio e um fim. Mas não escreva um romance (veja a diretriz n.º 1).
   • Início: isto dá ao leitor algum contexto. Sobre o que é este artigo e porque é que me devo importar? Seja breve.
   • Meio: As instruções vão aqui. Isto deve responder a "Como faço isto?"
   • Fim: Existem próximos passos para o artigo ou funcionalidade? Diga ao leitor para onde ele ou ela deve ir a seguir se quiser saber mais.

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

Estilo de escrita (abrangente)

• Estilo de escrita conversacional – Use um estilo informal e ativo, semelhante à forma como falaria com alguém pessoalmente.
• Humor e emoção – Usar humor é ótimo, mas por 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 aprendizagem – Tal como na escola, as pessoas aprendem de forma diferente. Além disso, todos beneficiam ao ver o mesmo conteúdo expresso de várias maneiras.
• Repetição – Quando explica algo de uma forma diferente com diferentes meios, está também, obviamente, a repeti-lo, o que é outra boa maneira de ajudar as pessoas a lembrarem-se do que é importante.
• Imagens e vídeo – Usar imagens e vídeo juntamente com texto não é apenas a melhor alternativa a ajudar pessoalmente, é uma forma fácil de incluir múltiplos estilos de aprendizagem e repetição. Demasiadas imagens, no entanto, podem tornar a localização de um artigo mais difícil, por isso tente adicionar imagens apenas quando for útil para um passo ou conceito. Por exemplo, para um passo que consiste em clicar num botão, pode dizer "Clique em OK" em vez de adicionar uma captura de ecrã da caixa de diálogo desse botão.
• Atividades – Especialmente num 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 os nossos artigos da base de conhecimento tem muitos benefícios, incluindo a facilidade de navegação e a melhoria da clareza e organização, além de nos ajudar a criar conteúdo de forma mais eficaz. Estamos a fazer a transição para a categorização de artigos externos da base de conhecimento em quatro tipos, cada um servindo um propósito específico:

• Sobre: Estes artigos abordam questões do tipo "O que é...", fornecendo informações essenciais para ajudar os leitores a entender um tópico.
• Como fazer: Estes artigos focam-se em responder a perguntas do tipo "Como fazer...?", guiando os leitores através dos passos necessários para alcançar um objetivo ou procedimento específico.
• Resolução de problemas: Estes artigos ajudam os utilizadores a identificar, diagnosticar e resolver problemas comuns que possam encontrar com um produto, serviço ou funcionalidade, abordando questões do tipo "Como fazer...?" relacionadas com a resolução de problemas.
• FAQ: Estes artigos contêm respostas concisas a perguntas frequentes sobre um único tópico, que podem não se enquadrar noutros artigos individuais da KB, fornecendo uma referência rápida para questões 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 contacto de um utilizador com o seu artigo da KB. Um bom título não deve apenas captar a atenção do leitor, mas também servir como uma pré-visualização concisa e informativa do conteúdo do artigo. Ao criar títulos para o `SUMO`, considere o seguinte:

• Clareza e Descrição: Corresponda ao tema do artigo e ao que o utilizador está a pesquisar. Seja conciso, mas focado no utilizador.
• Inclusão de Palavras-chave: Incorpore palavras-chave relevantes para melhorar a visibilidade nos motores de busca e ajudar os utilizadores a encontrar o seu artigo.
• Conciso: Mantenha os títulos breves, mas fornecendo informações adequadas. Títulos mais curtos são muitas vezes mais fáceis de usar. Tente manter os títulos com cerca de 60 caracteres.
• Orientado para a ação: Use verbos de ação quando aplicável para indicar o que os utilizadores podem fazer para resolver um problema ou alcançar um objetivo. Evite usar gerúndios (palavras terminadas em "ing") nos títulos para garantir que permanecem orientados para a ação. Evite usar títulos que contenham "Como fazer...".

Escreva uma boa introdução

Juntamente com o título e o índice, a introdução é o que ajudará o utilizador a determinar se está no lugar certo.

• Para um artigo "Sobre": Forneça uma visão geral textual ou definição do conceito e foque-se no porquê de o utilizador se dever importar com ele.
• Para um artigo "Como fazer": Forneça uma visão geral textual ou definição da tarefa e foque-se na importância ou benefícios da tarefa.
• Para um artigo de "Resolução de problemas": Descreva o problema específico ou os sintomas que os utilizadores podem encontrar. Escreva numa linguagem clara e concisa, evitando jargão técnico sempre que possível.

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

Organize o artigo eficazmente

A ideia geral aqui é tentar construir competências do simples para o complexo, enquanto tenta manter a informação necessária para a maioria das pessoas perto do topo. Assim, uma solução simples e comum viria geralmente antes de uma solução complexa ou de um caso extremo.

Torne as instruções passo a passo fáceis de seguir

O principal a ter em mente ao escrever instruções passo a passo é ter o cuidado de incluir todas as ações necessárias para completar a tarefa. Se, por exemplo, tiver de clicar em OK depois de selecionar uma preferência para passar para o passo seguinte, certifique-se de que inclui o clique em "OK" como parte desse passo. Algumas coisas adicionais a considerar:

• Existem sempre várias maneiras de alcançar um resultado. Devemos sempre escolher a forma mais amigável para o utilizador, usando a interface gráfica do utilizador e os menus sempre que possível.
• Use frases completas ao descrever como aceder à interface do utilizador.
• Inclua os resultados esperados ao dar instruções (por exemplo, Clique em "OK" e a janela fechar-se-á.).

Legibilidade

O texto deve ser legível. Para fazer isto, 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, não o deve expandir artificialmente. Forneça apenas informações úteis, valiosas e necessárias.

Como ligar a documentação externa para software de terceiros

Ao criar ou atualizar artigos que envolvem ações em software de terceiros, como sistemas operativos ou aplicações externas, é crucial fornecer aos utilizadores informações precisas e fiáveis. No entanto, incluir passos diretos para este software nos nossos artigos pode apresentar desafios:

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

Melhores práticas

Para garantir que os nossos utilizadores recebem a informação mais fiável e atualizada sem sobrecarregar os nossos recursos, siga estas melhores práticas:

• Ligar a recursos oficiais: Sempre que as instruções envolverem software de terceiros, encontre a documentação oficial ou os artigos de ajuda fornecidos pelo fabricante do software. Ligue a estes recursos em vez de escrever os passos diretamente nos nossos artigos.
• Fornecer contexto: Explique brevemente por que está a direcionar o utilizador para uma página externa (por exemplo: "Para os passos mais recentes e precisos para ajustar as suas definições de sistema, por favor, consulte a página de suporte oficial do <nome do software>").
• Verificar ligações periodicamente: Embora o nosso objetivo seja reduzir a manutenção de instruções de terceiros, verificar periodicamente se as ligações externas ainda são válidas continua a ser importante. Se notar que uma ligação ficou desatualizada ou quebrada, procure uma ligação atualizada para a documentação oficial e submeta uma revisão.
• Aviso sobre conteúdo externo: Ao direcionar os utilizadores para uma ligação externa, deixe claro que eles estarão a sair 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 esta ligação irá redirecioná-lo para um website externo que não é operado pela `Mozilla`.").

Exemplo

Imagine que está a escrever um artigo sobre a configuração de uma funcionalidade do `Firefox` que depende da alteração de definições ao nível do sistema num Mac. Em vez de delinear os passos diretamente no artigo, pode escrever:

Para os passos mais recentes sobre como ajustar as suas preferências de sistema no macOS, por favor, consulte a documentação de suporte oficial da Apple visitando este guia. Por favor, note que seguir essa ligação irá direcioná-lo para um website externo que não é operado pela `Mozilla`.

Isto garante que está a seguir as instruções mais atuais diretamente da fonte.

Diretrizes técnicas

• Para aprender como criar um novo artigo, consulte Criar um novo artigo na Base de conhecimentos.
• Para aprender como editar um artigo existente, consulte Editar um artigo da Base de Conhecimento.
• Consulte About the Knowledge Base para uma visão geral de como a Base de Conhecimento funciona.
• Consulte Melhorar a Base de conhecimentos 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. O seu título pode ser mais longo do que isto, se necessário, mas certifique-se de que as suas palavras-chave importantes estão incluídas nos primeiros 60 caracteres.
• Maiúsculas: A primeira palavra no título deve ser maiúscula, assim como os nomes próprios e nomes, não todas as palavras principais. Use o estilo de "frase", não o estilo de "título". (O mesmo se aplica aos títulos de cabeçalho. Consulte a secção Guia de estilo e regras de cópia abaixo para outras regras sobre maiúsculas.) Não edite, no entanto, o título de um artigo existente para alterar as maiúsculas, a menos que faça outras alterações no título, uma vez que não será criado um redirecionamento e resultarão ligações wiki quebradas em artigos que ligam para lá (bug 1969540).
• Não use dois pontos no título do artigo, pois isso impede a criação de uma ligação wiki para esse artigo (bug 749835). Certifique-se também de que não tem espaços extra no título do artigo, o que também impedirá que as ligações wiki funcionem.
• Tente variar a forma como 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 com "ing", como "Definir a página inicial".
• Lembre-se de que a explicação inteira não precisa de ir para o título. Pode usar o resumo para dar ao utilizador informações adicionais sobre o que está no artigo.

Slug

Quando cria um novo artigo e insere um título, o `SUMO` criará automaticamente um slug (a parte depois de kb/ no final do 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 (isto é por design). O slug tem um limite de 50 caracteres. Os espaços são renderizados como traços. O slug deve ser consistente com o título, mas, dada a restrição de espaço mais apertada, não precisa de ser o mesmo.

Corrigir o slug

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

Atualizar o slug de um artigo existente

Quando atualiza 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 já não se alinha com o slug existente. Manter o slug consistente ajuda a evitar ligações quebradas e preserva o valor de SEO.

Categorias, produtos e tópicos

Na maior parte, um artigo pertence à categoria Como fazer ou Resolução de problemas. Ocasionalmente, escrevemos artigos numa 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 "sub-tópico".

Palavras-chave

O campo de palavras-chave num artigo pode ser usado para melhorar os resultados de pesquisa no `SUMO`. No entanto, deve ser usado apenas em circunstâncias específicas, pois o uso indevido pode realmente prejudicar a pesquisa. Raramente precisamos de usar palavras-chave. Para mais detalhes, consulte Quando e como utilizar as palavras-chave para melhorar a classificação de pesquisa de um artigo.

Escreva um bom resumo de pesquisa

O resumo do artigo, juntamente com o título, ajuda os utilizadores a julgar se um artigo responderá à sua pergunta. Chamamos a isto "Confiança do Utilizador" e impacta diretamente as taxas de cliques. Mesmo que apresentemos o artigo correto no topo da lista de resultados de pesquisa, o utilizador precisa de 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 resolução de problemas deve tentar incluir sintomas. Além disso, um resumo deve seguir estas diretrizes:

• Curto e direto ao ponto. Lembra-se dos anúncios classificados? Escreva-o assim. Os motores de busca podem cortar qualquer coisa com mais de 140 caracteres. Se usar um resumo mais longo, mantenha a informação importante no início. Nota: O software da KB mostrará 20 caracteres restantes quando o resumo atingir 140 caracteres, porque o limite de pesquisa interno é 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 considerar:
  • Nós vamos mostrar-lhe
  • Nós vamos explicar
  • Esta página explica
  • Este artigo descreve
  • Aprenda como

Número de passos

Ao guiar os utilizadores através de um processo, considere listas ordenadas (listas numeradas). É geralmente uma boa prática tentar manter o número total de passos no intervalo de seis a sete.

Estrutura paralela

Use a mesma formulação ou padrão de palavras para cada passo que escreve. A estrutura paralela é importante nos artigos da KB porque torna as coisas claras e fáceis de seguir. Quando elementos semelhantes têm um formato consistente, os utilizadores podem entender e completar tarefas mais suavemente. Esta estrutura simplifica as instruções, reduz erros e garante que a informação é transmitida eficazmente.

Por exemplo:

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

Pistas direcionais

As pistas direcionais são referências ou indicadores que guiam os utilizadores para a localização ou posição específica dentro de uma interface de utilizador onde precisam de realizar uma ação particular. Estas pistas ajudam os utilizadores a navegar e interagir com software, aplicações ou websites de forma mais eficaz. Elas incluem tipicamente frases como "No canto superior direito", "No menu do lado esquerdo" ou "Abaixo da barra de pesquisa", que fornecem aos utilizadores uma noção clara de onde encontrar e realizar ações.

Nas suas instruções de artigos da KB, 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 utilizadores a localizar e realizar ações facilmente dentro da interface.

Guia de estilo e regras de cópia

Como dissemos antes, deve usar um estilo ativo e conversacional quando escreve. Evite dizer coisas como "Se os marcadores de um utilizador foram perdidos" e, em vez disso, diga "Se perdeu os seus marcadores". Aqui estão outras questões comuns de estilo e cópia que pode encontrar ao escrever artigos de suporte: Use sempre os termos da forma como aparecem na interface da `Mozilla`. Por exemplo:

• Plugins não tem hífen.
• Add-ons tem hífen.
• Home page (página inicial) são duas palavras.

Termos gerais de computação:

• Website é uma palavra. Web page (página da Web) são duas palavras.
• Log in e log out são verbos. Exemplo: "Faça log in no website." 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.

As ligações 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 ligações em frases:

• Evite usar "clique aqui" ou "aqui" como texto da ligação.
  • Faça: Vá para as definições da sua conta para cancelar a sua subscrição.
  • Não faça: Clique aqui para cancelar a sua subscrição.

Coloque em maiúscula os seguintes itens:

• Nomes próprios e nomes, incluindo nomes de marcas, nomes de produtos e nomes de funcionalidades
• A primeira palavra de uma frase completa
• As letras de abreviaturas e acrónimos, a menos que sejam normalmente em 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 a seguir a dois pontos
• A primeira palavra num 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.
• Use sempre "sign in" e "sign out".
• Na forma verbal, use "sign in to your account" (não "sign into") para ser gramaticalmente correto.
• Também pode usar "Sign in with `Mozilla`".
• "Sign" deve ser sempre usado como verbo. Se o estiver a usar como substantivo, use "login".
• Use "sign up" como a chamada à ação para criar uma nova conta.

Para detalhes sobre como se referir a `Mozilla accounts` em artigos da KB, consulte Editorial guidelines for Mozilla accounts.

Não use “i.e.” e “e.g.”. Estas abreviaturas latinas podem confundir as pessoas. Para maior clareza, use "por 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 em série numa lista de itens. Por exemplo, use "Extensões, temas e plugins" (sem a vírgula em série), não "Extensões, temas, e plugins".

Use inicialismos que são considerados geralmente compreendidos. 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 as instruções na voz ativa. Escreva as 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" não "O `Firefox` tem de 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 Coloque em maiúscula a 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 muitas línguas diferentes, por isso 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 alcançados adicionando a marcação wiki adequada ao redor do item. Consulte a Cábula de marcação para os estilos mais comuns.

Temos uma marcação wiki especial – {for} – que lhe permite direcionar informações para versões específicas do `Firefox` ou sistemas operativos específicos. Por exemplo, pode exibir um conjunto de instruções para pessoas que usam o Windows e outro para pessoas que usam o macOS (consulte Como utilizar o "For" para mais detalhes).