Para escrever bem textos técnicos, você precisa baixar as expectativas [Tradução]

1. Escrever é uma habilidade essencial para engenheiros

   • A escrita técnica é indispensável para engenheiros de todos os níveis, de mensagens de commit à documentação.
   • A diferença entre escrever bem e não escrever bem tem grande impacto na eficiência do trabalho e na comunicação dentro da organização.

2. Seja o mais conciso e breve possível

   • Os leitores não dedicam muito tempo a um texto.
   • Se você consegue transmitir uma ideia em uma frase, faça isso.
   • Omitir alguns detalhes de propósito pode, na verdade, ser uma vantagem.
   • Coloque o conteúdo importante no início do texto, na primeira frase ou no título.

3. Defina expectativas realistas

   • Não espere que as pessoas leiam um texto técnico com atenção total e o compreendam completamente.
   • Em organizações de engenharia, confusão e diferenças de entendimento são normais, e a escrita não consegue nivelar todo mundo.
   • Ao baixar as expectativas, a comunicação acaba sendo mais eficaz.

4. O objetivo do texto é transmitir claramente o ponto central

   • O objetivo prioritário é transmitir a uma equipe ampla um ponto extremamente simples, como “adicionar configuração é complicado”.
   • Mais importante do que levar todos a uma compreensão técnica completa é fornecer o contexto mínimo necessário para gerar confiança.

5. O efeito que realmente se pode esperar

   • Em geral, quem recebe o texto tem menos conhecimento de contexto do que quem o escreveu.
   • Para um público amplo, é possível transmitir uma mensagem simples; para um grupo muito pequeno, é possível comunicar claramente conteúdos complexos.
   • Só de destacar os pontos essenciais já se produz uma grande diferença em organizações de grande porte.

6. Pensamento claro produz texto claro

   • É difícil condensar um tema que ainda não foi suficientemente compreendido.
   • Reconheça as incertezas e concentre-se nas partes que você consegue explicar com clareza.

7. Erros comuns e recomendações

   • Não fique obcecado em transmitir detalhes demais.
   • Resuma gradualmente o que você quer comunicar em uma frase, um parágrafo e uma página, e entregue primeiro o essencial.
   • Há valor, por si só, em transmitir o contexto geral até mesmo para quem quase não tem conhecimento técnico de base.

[yeobi222]

A maior questão é como incluir explicações adicionais para facilitar o entendimento
Quando a pessoa que toma a decisão é leiga na área...

[girr311]

Isso se aplica não apenas à documentação técnica, mas à maioria dos textos em geral.