Olá a todos! Bem-vindos de volta à nossa série sobre redação técnica. Na nossa última lição, focamos em abraçar a clareza; hoje vamos falar sobre sua prima próxima, a consistência.
Imagine que você está lendo o manual de usuário de um novo software. Na página um, o botão que você precisa clicar se chama OK. Na página três, ele se chama Confirmar. E na página cinco, é apenas ✓. Confuso, né? Este é um exemplo clássico de inconsistência, e pode causar frustração séria para seus usuários.
Na documentação técnica, consistência não é só sobre boa gramática; é sobre previsibilidade e confiança. Quando sua documentação é consistente, seus leitores sabem o que esperar. Eles conseguem aprender sua terminologia e navegar pelo seu conteúdo com confiança, sem ter que parar e adivinhar o que você quer dizer.
Por que a consistência importa na documentação
- Constrói confiança: Quando seus documentos são consistentes, isso faz seu produto parecer mais profissional, polido e confiável.
- Reduz a confusão: Os usuários não precisam perder tempo tentando descobrir se termos diferentes significam a mesma coisa.
- Melhora a experiência do usuário: Torna sua documentação mais fácil de ler e acompanhar, tornando a jornada do usuário mais fluida.
- Ajuda na leitura rápida: Formatação consistente ajuda os leitores a escanear documentos rapidamente para encontrar o que procuram. A maioria das pessoas não lê os documentos do início ao fim, apenas os escaneia em busca de respostas para suas perguntas.
Os pilares da consistência
Vamos dividir a consistência em 4 áreas principais nas quais você pode começar a focar agora mesmo:
- Gramática e ortografia
- Terminologia
- Formatação
- Tom e voz
1. Gramática e ortografia
Você consegue perceber a diferença quando usa errado "mas" (ou é "mais"?) na sua escrita? Usar gramática e ortografia corretas não só faz seus documentos parecerem polidos e bem escritos, como também os torna mais fáceis de entender e de traduzir para outros idiomas. Com o crescente uso de resumos e agentes de IA, garantir a gramática correta é vital para uma comunicação clara e eficaz!
Erros de ortografia podem ser muito constrangedores para a empresa e para você como redator. Então, sempre faça uma revisão ortográfica manual, mesmo quando você tem um software corretor excelente.
Dica: Melhorar sua gramática, não só na documentação formal mas nas suas conversas diárias, e-mails e mensagens, é a forma mais eficaz de aprimorar suas habilidades de escrita.
2. Terminologia
Se você chama um botão de Salvar em um lugar, chame-o de Salvar em toda a sua documentação técnica. Crie uma pequena lista de termos-chave ou glossários para o seu projeto e siga-os. Isso inclui nomes de produtos, nomes de funcionalidades e termos técnicos. Você não precisa criar um glossário enorme da noite para o dia, apenas comece com os termos mais importantes e continue adicionando conforme necessário.
3. Formatação
Como você destaca código? Em blocos de código? Uma fonte diferente? Tome uma decisão e mantenha-a. Você usa negrito para elementos de interface? É sua escolha, mas seja consistente em toda a sua documentação. Isso se aplica a títulos, marcadores, listas numeradas e até a forma como você usa pontuação.
4. Tom e voz
Voz é a personalidade da sua documentação. Isso permanece consistente em todo o seu conteúdo. A voz deve ser clara, direta, evitar jargões, etc. O tom pode mudar dependendo do tipo de documento; por exemplo, um tutorial pode usar um tom conversacional, enquanto um guia de solução de problemas pode usar um tom mais direto e calmo. Leia mais sobre isso no Guia de Documentação para Desenvolvedores do Google.
Dica prática: comece um guia de estilo
A melhor forma de garantir consistência é criar um guia de estilo simples aplicável à sua equipe ou organização. Sua empresa tem um guia de estilo disponível publicamente? Se sim, inspire-se nele ou você pode usar muitos dos guias de estilo disponíveis online também.
Você deve documentar as nuances específicas da empresa ou equipe no seu guia de estilo. Isso não precisa ser um documento de 100 páginas. Pode ser um simples documento compartilhado ou uma página do Notion que lista seus termos-chave, regras de formatação e tom preferido.
Por exemplo:
Dica: você pode ir um passo além e adicionar essas regras de estilo ao seu linter se estiver seguindo uma abordagem docs-as-code para sua documentação técnica!
Ao focar na clareza, você estará no caminho certo para criar documentação que não é apenas clara, mas também confiável e profissional. Boa sorte na sua jornada de redação técnica, pense sobre quais itens você pode colocar no seu guia de estilo e comece hoje mesmo!
Me conte nos comentários quais outros temas relacionados à escrita você tem interesse em entender.