Como escrever artigos da Base de conhecimentos

Existem muitas coisas a balançar ao escrever ou editar um artigo da Base de conhecimentos do Apoio da Mozilla ("SUMO"). Você quer ser completo, conciso, factual, e cativante, tudo ao mesmo tempo! Não é certamente a coisa mais fácil de se fazer no mundo. Aqui estão algumas guias de orientação para ajudar a tornar esse balanço um pouco mais fácil. Além disso, isto é uma wiki e nós podemos sempre revisar algo se estivermos errados.

• Para saber como realmente criar um novo artigo, consulte Criar um novo artigo na Base de conhecimentos.
• Consulte Como funciona a Base de conhecimentos para uma visão geral.
• Pode consultar uma lista completa de documentação de artigos aqui: Melhorar a Base de conhecimentos

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

Queremos que os nossos artigos sejam úteis para toda a gente, e não apenas para utilizadores avançados. Isto significa que estamos a escrever para um público geral em vez de apenas um familiarizado com terminologia e técnicas de computador. Assuma que a pessoa para a qual está a escrever não sabe como alterar preferências ou adicionar um botão de barra de ferramentas sem instruções passo-a-passo. Além disso, devemos assumir que estas pessoas não alteraram nenhuma das aplicações predefinidas ou definições do sistema operativo.

Escolha um bom título

O título do artigo, junto com o resumo, são as únicas coisas que o utilizador tem que avaliar, quer o artigo responda ou não à sua questão. Chamamos isto de "Confiança do utilizador" e tem um impacto direto no número de cliques. Mesmo que coloquemos o artigo correto no topo da lista dos resultados de pesquisa, o utilizador tem que fazer a ligação mental entre os termos pesquisados e os resultamos que apresentamos para que cliquem no artigo.

O título deve tentar descrever o assunto tratado no artigo. O importante é que as primeiras palavras sejam o mais compreensíveis quanto possível, contendo palavras-chave importantes. Isto irá permitir aos utilizadores reconhecer o assunto do artigo e clicar com confiança. Para além disso, um título deve seguir estas guias de orientação:

• Comprimento do título: A página dos resultados de pesquisa do Google irá mostrar até 70 caracteres. O título pode ser maior do que isto, se necessário, mas certifique-se de que palavras-chave importantes sejam incluídas nos primeiros 70 caracteres.
• Capitalização: A primeira palavra e nomes próprios no título deverão ser capitalizados, não todas as palavras (utilize o estilo de "frase" style, não o estilo de "cabeçalho"). Consulte a secção do guia de estilo do SUMO abaixo para outras regras acerca da capitalização.
• Não utilize dois pontos ":" no título do artigo, visto que impede que se crie uma URL para esse artigo (bug 749835).
• Certifique-se de que não existem espaços extra no título do artigo. Isto impede também as ligações da wiki de funcionarem.
• Tente variar o modo como nomeia os artigos. Não utilize os mesmos verbos ou frases em todos os títulos.
• Tente não utilizar palavras “-endo”.

Lembre-se de que a explicação complete não tem que ser incluída no título. Pode utilizar o resumo para fornecer a informação adicional ao utilizador sobre o que está descrito no artigo.

Corrija o slug

Quando você cria um título, o SUMO irá criar automaticamente um slug (o final do URL par ao artigo). O slug tem um limite de 50 caracteres. Os espaços são substituídos por hífenes. O slug deve ser consistente com o título, mas devido ao espaço restrito permitido, não é obrigatório ser exatamente igual ao título. Verifique o final do slug gerado automaticamente. Por vezes, uma palavra é cortada ou termina com um hífen. Por favor, corrija detalhes como estes.

Categorias, produtos e tópicos

Na sua maioria, um artigo pertence à categoria "Como fazer" ou "Solucionar problemas". Ocasionalmente, escrevemos artigos sobre "Como contribuir" (tal como este) ou algo numa das categorias.

Os artigos são também "relevantes para" pelo menos um produto. Estes pertencem também a um "Tópico" principal e, opcionalmente, um "sub-tópico".

Palavras-chave

O campo das palavras-chave num artigo pode ser usado para melhorar os resultados de pesquisa no SUMO. No entanto, este deverá ser utilizado apenas sob circunstâncias específicas, visto que um uso indevido pode, de facto, prejudicar a pesquisa. Raramente precisamos de utilizar palavras-chave. Para detalhes, consulte Quando e como utilizar palavras-chave para melhorar o ranking de pesquisa de um artigo.

Escreva um bom resumo de pesquisa

O resumo do artigo, juntamente com o título, são as únicas coisas que o utilizador tem que avaliar se um artigo irá ou não responde à sua questão. Chamamos a isto de "Confiança do utilizador" e tem um impacto direto no número de cliques. Mesmo que o artigo correto apareça no topo da lista dos resultados de pesquisa, o utilizador necessita de fazer a ligação mental entre os termos da pesquisa e os resultados apresentados para que cliquem no artigo.

Um resumo para um artigo sobre "Como fazer" deverá incluir os tópicos abrangidos no artigo. Um artigo de diagnóstico e solução de problemas deverá tentar incluir os sintomas. Para além disso, um resumo deverá seguir estas guias de orientação:

• Ser sucinto e direto ao assunto. Lembra-se dos anúncios de classificados? Escreva-o da mesma forma. Os motores de pesquisa poderão cortar qualquer coisa maior do que 140 caracteres. Se escrever um resumo maior, mantenha a informação importante no início. Nota: O software da Base de conhecimentos irá mostrar 20 caracteres de fora quando o resumo atingir 140 caracteres, porque o limite de pesquisa interno é de 160 caracteres.
• Não utilize a marcação da wiki.
• Não utilize "Este artigo explica" em todos os resumos, mas sim, varie sempre que possível. Algumas outras frases a considerar:
  • Iremos mostrar-lhe
  • Iremos explicar
  • Esta página explica
  • Este artigo descreve
  • Saiba como

Torne a sua escrita cativante

A Base de conhecimentos é um repositório de informação técnica sobre a operação das aplicações Mozilla. A documentação lista as funções de várias funcionalidades, procedimentos de diagnóstico e instruções para resolver problemas frequentes. A documentação pode ser acedida utilizando a função de pesquisa em cada página ou você pode apenas atirar o seu computador pela sala, onde os unicórnios irão usar os seus poderes de arco-íris para transformá-la num doce mágico que, uma vez que consumido, irá torná-lo num ninja de computadores de nível 70.

Acordou agora? Ainda bem.

Esse parágrafo parece uma leitura aborrecida, pelo menos até os unicórnios aparecerem. Utilizar o humor e emoção (SURPRESA!) são algumas das técnicas que podemos utilizar para cativar as pessoas. Estas técnicas, listadas abaixo, todas têm o objetivo de que o seu cérebro esteja atento, recreando o que esta interação poderia ser se estivesse a acontecer pessoalmente. Quando o fazemos, a informação é mais fácil de compreender e de memorizar.

• Estilo de escrita de conversação – Use um estilo informar e ativo, semelhante ao modo como você falaria para alguém pessoalmente.
• Humor e emoção – Usar o humor é bom, mas às vezes é difícil ou impossível de traduzir. As emoções, como as surpresas, e o "Não sabia disso!" (não tenho a certeza de como chamar essa emoção) podem ser fáceis de incluir.
• Vários estilos de aprendizagem – Tal como na escola, as pessoas aprendem de formas diferentes. Também, todos beneficiamos de ver o mesmo conteúdo expressado em formas diferentes.
• Repetição – Quando você explica algo de uma forma diferente, com ficheiros multimédia diferentes, está obviamente a repeti-lo, o que uma outra forma de ajudar as pessoas a memorizar o que é importante.
• Imagens e vídeo – Utilizar imagens e vídeo para explicar as coisas, juntamente com o texto, não é apenas a melhor opção para ajudar as pessoas, assim como é também um modo fácil de incluir vários estilos de aprendizagem e de repetição.
• Atividades – Especialmente num tutorial, é bom dar às pessoas algo útil para conquistar. Uma coisa é ler instruções e compreender o processo, mas é muitas vezes útil relembrar e permitir às pessoas experimentarem as coisas.

Escreva uma boa introdução

Juntamente com o título e a tabela de conteúdos, a introdução é o que as pessoas irão utilizar para determinar rapidamente se estão no lugar certo.

• Para um tutorial ou artigo de "Como fazer": Forneça um breve resumo sobre que coisas serão aprendidas.
• Para um artigo de referência: Forneça uma explicação breve da funcionalidade.
• Para um artigo de diagnóstico: Forneça um breve resumo do problema e os seus sintomas.

Normalmente, uma boa introdução pode servir com um bom resumo de pesquisa. Muitas vezes basta copiá-la para o campo de "Resumo dos resultados de pesquisa" e já está.

Organize o artigo com eficácia

A ideia geral aqui é tentar criar competências desde o simples ao mais complexo, ao mesmo tempo que se tenta manter a informação necessária pela maioria das pessoas perto do topo. Deste modo, uma solução simples e frequente normalmente viria antes de uma solução complexa ou de extremos.

Utilize títulos de cabeçalho descritivos

Os nossos artigos são normalmente compreensíveis, por isso é importante utilizar cabeçalho descritivos para ajudar as pessoas a encontrar a parte do artigo que necessitam. Dê uma olhada na sua tabela de conteúdos. A introdução funciona em dar-lhe uma boa visão geral do objetivo do artigo?

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

A coisa principal a ter em atenção 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, você tiver que clicar em "OK" após selecionar uma preferência para poder seguir para o passo seguinte, certifique-se de incluir o "OK" como parte desse passo. Algumas coisas adicionais a considerar:

• Existem sempre várias formas de atingir um resultado. Devemos escolher sempre a forma mais simples e fácil, utilizando a interface gráfica do utilizador e menus quando possível.
• Utilize frases completas ao descrever como aceder a interface do utilizador.
• Inclua resultados previsíveis ao dar instruções (por exemplo, Clique em "OK" e a janela irá fechar.).

Guia de estilo do SUMO

Como mencionámos anteriormente, deverá utilizar um estilo de conversação e ativo ao escrever. Evite dizer coisas como "Se os marcadores de um utilizador foram perdidos" e em vez disso "Se perdeu os seus marcadores". Estes são outros problemas de estilo frequentes que poderá encontrar ao escrever artigos de suporte (se não encontra aqui o seu problema, existe ainda um Guia de estilo da Mozilla (em inglês)):

Utilize sempre os termos no modo como estes aparecem na interface da Mozilla. Por exemplo:

• Plugins não têm um hífen.
• Extras têm um hífen.
• Página inicial são duas palavras.

Termos gerais de computação:

• Internet escreve-se com letra maiúscula.
• Website é uma palavra.
• Iniciar e terminar são verbos. Exemplo: "Iniciar sessão no website."
• Iniciar sessão e terminar sessão são nomes (normalmente usados como adjetivos). Exemplo: "Clique no botão de inicio de sessão."
• Utilize email em vez de e-mail.
• O plural de CD-ROM é CD-ROMs.

As ligações para o mozilla.org não devem incluir o idioma:

• Utilize https://www.mozilla.org/ em vez de https://www.mozilla.org/pt-PT/

Capitalize os seguintes itens:

• Nomes próprios
• A primeira palavra de uma frase completa
• As letras de abreviações e acrónimos, a não ser que sejam normalmente com letra minúscula
• A primeira palavra em listas numeradas ou de marcadores
• O nome de uma tecla do teclado
• A primeira palavra de uma frase completa seguida de dois pontos
• A primeira palavra num cabeçalho ou título

Não utilize "ex.". Estas abreviações latinas podem confundir as pessoas. Para uma maior clareza, utilize "noutras palavras" ou "explicando de um outro modo" em vez de ex., quando você quer explicar algo de um modo diferente. Utilize "por exemplo" ou "tais como" em vez de ex. quando quer dar exemplos.

Não utilize vírgulas numa lista de itens. Por exemplo, use "Extensões, temas e plugins" (sem a vírgula), e não "Extensões, temas, e plugins".

Temos estilos visuais especiais para um número de itens que podem ser acedidos adicionando a marcação de wiki apropriada em torno do item. Consulte o artigo Folha de consulta de linguagem de marcação para conhecer os estilos mais frequentes.

Temos uma marcação de wiki especial – {for} – que lhe permite direcionar informação para versões específicas do Firefox ou sistemas operativos específicos. Por exemplo, você mostra um conjunto de instruções para pessoas que usam o Windows e outro para pessoas que usam o Mac OS X (consulte Como utilizar o código "for" para detalhes).