Lição 1: Seus primeiros passos para uma escrita clara
Olá, engenheiros de software! Se a ideia de escrever documentação técnica (também conhecida como redação técnica) te dá vontade de gritar no vazio, esta série é para você. Eu divido o processo de escrita em artigos curtos, para que pareça menos uma tarefa assustadora e mais um desafio interessante para conquistar.
Só para lembrar, você não está começando do zero. Você já tem muitas das habilidades necessárias para ser um ótimo redator técnico. Vocês são mestres da lógica e de criar soluções elegantes em código. Estão acostumados a ser precisos, a decompor problemas complexos e a explicar sistemas intrincados. É exatamente disso que se trata a boa redação técnica; só que com palavras em vez de ponto e vírgula!
Sua primeira missão: abrace a clareza
A clareza é a base de uma boa redação técnica. Seu objetivo é este: qualquer pessoa que leia sua documentação deve entender exatamente do que você está falando, sem nenhuma confusão. Seja um colega de equipe, um novo desenvolvedor entrando no projeto, ou um usuário final; foque em tornar o documento compreensível para eles!
Para tornar seus documentos técnicos mais claros, aqui estão 5 pontos simples nos quais você pode focar:
1. Conheça seu público (mesmo que seja você mesmo no futuro!): Para quem você está escrevendo? Qual é o nível de entendimento técnico dele? Tenha isso em mente ao escolher suas palavras e explicar conceitos. Um bom truque é que a maioria dos documentos técnicos para o usuário final assume que o nível de leitura do usuário está entre o 8º e o 10º ano. Isso significa que um aluno médio do 8º ano consegue entender seu material! Se for material altamente técnico, o nível pode ser mais alto, entre o 10º e o 12º ano. Use verificadores de legibilidade, como o Hemingway, para ver o nível de leitura.
2. KISS (mantenha simples e direto!): Evite jargões e frases excessivamente complexas. Imagine que você está explicando para alguém inteligente, mas que talvez não tenha tempo de ler o documento várias vezes. Isso é especialmente verdadeiro quando seu público é um usuário final e não está familiarizado com sua indústria ou tecnologia.
3. Uma ideia por frase: Frases curtas e focadas são mais fáceis de entender. Quando você divide informações complexas em partes menores e mais gerenciáveis. Uma regra prática é: se uma frase ficar mais longa que 1,5 linhas na sua página (no MS Word ou Google Docs), reescreva-a como duas frases.
4. A estrutura é sua amiga: Use títulos, subtítulos, marcadores e listas numeradas para organizar suas informações de forma lógica. Isso facilita para os leitores escanearem e encontrarem o que precisam. Pense nisso como dividir informações em partes menores e mais legíveis, em vez de uma grande página de texto que obriga o leitor a usar mais das suas habilidades cognitivas para entender o texto à sua frente.
5. Use a voz ativa: A Voz Ativa torna sua escrita mais direta e fácil de acompanhar. Em vez de dizer "O programa foi implementado", use "Implementamos o programa".
Isso é tudo para nosso primeiro passo! Essas são ideias simples que qualquer pessoa poderia implementar. Comece focando em tornar suas explicações o mais claras e diretas possível. Experimente com suas tarefas de documentação esta semana.
Continue acompanhando esta série, e você verá que documentar seu ótimo trabalho não precisa ser intimidante. Na verdade, pode até ser recompensador! Na próxima parte, vamos nos aprofundar em outro aspecto fundamental da redação técnica: Pensar na documentação como uma forma de comunicação.