Tempo estimado: 10 minutos
Imagine que você acabou de escrever o primeiro rascunho de um documento. Como você melhora esse rascunho? Na maioria dos casos, trabalhar em direção a um documento final publicado é um processo iterativo. Transformar uma página em branco em um primeiro rascunho costuma ser o passo mais difícil. Depois de escrever um primeiro rascunho, reserve bastante tempo para refinar seu documento.
As dicas de edição nesta unidade podem ajudar a transformar seu primeiro rascunho em um documento que comunique mais claramente as informações de que seu público precisa. Use uma dica ou use todas; o importante é encontrar uma estratégia que funcione para você e, em seguida, tornar essa estratégia parte de sua rotina de escrita.
As dicas nesta unidade baseiam-se nas habilidades básicas de redação e edição do Módulo 1. Esta unidade inclui um resumo das técnicas de edição úteis desse curso. Para uma atualização mais detalhada, visite as unidades de autoestudo do Módulo 1.
Empresas, organizações e grandes projetos de código aberto frequentemente adotam um guia de estilo existente para sua documentação ou escrevem seus próprios. Muitos dos projetos de documentação no site do Google Developers seguem o Google Developer Documentation Style Guide. Se você nunca contou com um guia de estilo antes, à primeira vista o Google Developer Documentation Style Guide pode parecer um pouco intimidador, oferecendo orientações detalhadas sobre tópicos como gramática, pontuação, formatação e documentação de interfaces de computador. Você pode preferir começar adotando os destaques do guia de estilo.
Para projetos menores, como a documentação da equipe ou um pequeno projeto de código aberto, você pode descobrir que os destaques são tudo o que você precisa.
Algumas das diretrizes listadas nos destaques do guia de estilo são abordadas no Módulo 1. Você pode se lembrar de algumas das seguintes técnicas:
Os destaques do guia de estilo apresentam muitas outras técnicas que podem ser úteis ao escrever documentação técnica, como:
Quem é o seu público? Dê um passo para trás e tente ler seu rascunho do ponto de vista deles. Certifique-se de que o objetivo do seu documento seja claro e forneça definições para quaisquer termos ou conceitos que possam ser desconhecidos para seus leitores.
Pode ser útil definir uma persona para o seu público. Uma persona pode consistir em qualquer um dos seguintes atributos:
Você pode então revisar seu rascunho com sua persona em mente. Pode ser especialmente útil informar ao seu público sobre quaisquer suposições que você tenha feito. Você também pode fornecer links para recursos onde eles podem aprender mais se precisarem entender um assunto específico.
Observe que confiar demais em uma persona (ou duas) pode resultar em um documento muito focado para ser útil para a maioria de seus leitores.
Para uma atualização e mais informações sobre este tópico do Módulo 1, consulte a unidade Público.
Dependendo do contexto, o estilo de sua escrita pode alienar, envolver ou até mesmo entediar seu público. O estilo desejado de um determinado documento depende até certo ponto do público. Por exemplo, o guia do colaborador para um novo projeto de código aberto destinado a recrutar voluntários pode adotar um estilo mais informal e conversacional, enquanto o guia do desenvolvedor para um aplicativo corporativo comercial pode adotar um estilo mais formal.
Para verificar se sua escrita é conversacional, leia-a em voz alta. Preste atenção em frases estranhas, frases muito longas ou qualquer outra coisa que não pareça natural. Como alternativa, considere usar um leitor de tela para dar voz ao conteúdo para você.
Para obter mais informações sobre como ajustar o estilo de sua escrita para se adequar ao seu público, consulte Style and authorial tone.
Depois de escrever seu primeiro rascunho (ou segundo ou terceiro), deixe-o de lado. Volte a ele depois de uma hora (ou duas ou três) e tente lê-lo com novos olhos. Você quase sempre notará algo que poderia melhorar.
Alguns redatores gostam de imprimir sua documentação e revisar uma cópia em papel, com lápis vermelho na mão. Uma mudança de contexto ao revisar seu próprio trabalho pode ajudá-lo a encontrar coisas para melhorar. Para uma visão moderna dessa dica clássica, copie seu rascunho em um documento diferente e altere a fonte, o tamanho e a cor.
Assim como os engenheiros precisam de colegas para revisar seu código, os redatores precisam de editores para fornecer feedback sobre os documentos. Peça a alguém para revisar seu documento e fazer comentários específicos e construtivos. Seu editor par não precisa ser um especialista no assunto no tópico técnico do seu documento, mas ele precisa estar familiarizado com o guia de estilo que você segue.
Se você estiver trabalhando em um documento, use uma ou mais dicas desta página para melhorá-lo. Se você não tiver um documento em andamento, edite o parágrafo abaixo.
Determine se você pode ou não simplificar seu documento por meio do uso de terminologia equivalente, mas relativamente mais curta e, portanto, mais facilmente compreensível pelo seu público. É importante certificar-se de que seu documento seja editado antes de ser visto pelo seu público, que pode incluir pessoas menos ou mais familiarizadas com o assunto coberto pelo seu documento. A primeira coisa que você precisa é de um rascunho. Algumas coisas que podem ajudar a tornar seu documento mais fácil de ler são certificar-se de que você tenha links para informações básicas e também verificar se há voz ativa em vez de voz passiva. Se você tiver frases longas, considere encurtá-las ou implementar o uso de uma lista para facilitar a verificação das informações.
Para ajudar seu público a entender seu documento, aplique estes princípios básicos de edição:
O conteúdo desta página é uma tradução livre e adaptada. O material original está disponível em inglês no Google Developers sob a licença Creative Commons (CC BY 4.0).