Diretrizes gerais de redação
Siga estas diretrizes ao desenvolver conteúdo com os modelos do The Good Docs Project.
Linguagem e tom
Use linguagem, ortografia e tom consistentes em toda a documentação.
Descreva tudo da forma mais clara e precisa possível.
Passe o texto por um linter gramatical para verificar sua legibilidade.
Ferramentas como o Grammarly ajudam a identificar problemas gramaticais
Ferramentas como o
Valeajudam a identificar problemas de estilo.Este artigo apresenta uma lista de outras ferramentas de lint.)
Evite coloquialismos e jargões, pois eles dificultam a compreensão por pessoas que não têm o inglês como língua materna.
Evite usar siglas na documentação sem escrever a forma por extenso na primeira ocorrência. Nas referências seguintes, você pode usar a sigla.
Evite acrescentar opiniões próprias ou de terceiros. Isso prejudica a capacidade do leitor de tirar conclusões a partir da documentação.
Redação de etapas de procedimentos
Veja algumas recomendações para criar etapas de procedimentos:
Em procedimentos com muitas etapas, considere dividir o conteúdo em subseções de 5 a 10 etapas. Isso facilita a leitura e a memorização e dá ao leitor uma sensação de progresso após concluir cada bloco. A divisão em blocos é recomendada por grandes empresas, como no guia de estilo de redação da Microsoft, e pela pesquisa sobre divisão em blocos e usabilidade do Nielsen Norman Group.
Cada etapa deve ser uma única frase, que possa ser lida em voz alta e tenha sentido gramatical.
Ao descrever uma etapa, inclua uma frase introdutória para lembrar ao leitor o que ele fará ao seguir as subetapas.
Procure não usar mais de quatro subetapas em cada etapa principal.
Se estiver recuando subetapas além de um nível, reorganize-as em um novo bloco de etapa principal.
Um número excessivo de subetapas pode indicar que algumas delas devem formar uma nova seção de etapas.
Recomendam-se capturas de tela e imagens, especialmente quando for possível incluir destaques nas partes específicas da tela mencionadas.
Identifique as etapas opcionais digitando Opcional seguido de dois-pontos. Por exemplo,
Opcional: informe uma descrição para o repositório.
Use a oração condicional se (condição), então (resultado) para identificar etapas aplicáveis somente quando determinados critérios forem atendidos. Sempre comece as etapas condicionais pela condição, para que os usuários que não a atendam possam ignorá-las. Por exemplo,
Se você usa Windows, instale o programa de máquina virtual VirtualBox em seu computador.
Para obter mais informações sobre a redação de procedimentos, consulte o guia de estilo da documentação para desenvolvedores do Google.
Estrutura da página
Antes de começar a escrever, crie um esboço dos títulos que deseja incluir no documento.
Use o esboço para organizar suas ideias sobre os principais assuntos que precisa apresentar aos leitores.
É muito mais fácil reorganizar títulos do que mover blocos de conteúdo.
Você também pode perceber que precisa criar dois artigos caso o assunto comece a se ramificar.
Adicione à seção “Veja também” todos os links mencionados no corpo do conteúdo. Links em linha podem se perder em artigos longos, e procurá-los aumenta a carga cognitiva do público.
Títulos e nomes de arquivos
Faça com que o título descreva o conteúdo do artigo.
Use um título exclusivo no espaço da aplicação.
Mantenha o título e o nome do arquivo iguais: quando são diferentes, fica difícil identificar o nome do arquivo.
Use palavras exclusivas nos títulos para poder pesquisar e substituir o texto posteriormente sem obter correspondências aproximadas.
Veja alguns exemplos de títulos e as estruturas sugeridas para os nomes dos arquivos:
Usar uma torradeira
usar-uma-torradeira.rst
Torrar uma fatia de pão
torrar-fatia-de-pao.rst
Definições
Se você usa repetidamente determinados termos em um artigo longo, pode defini-los uma vez e depois reutilizá-los no corpo do texto.
Explore outros guias e modelos do The Good Docs Project.