Tempo estimado: 10 minutos
Nós pesquisamos documentações extensivamente, e acontece que as melhores frases do mundo consistem principalmente de palavras. (Sarcasmo…)
Ao escrever ou editar, aprenda a reconhecer termos que podem ser desconhecidos para alguns ou todos os seus públicos-alvo. Ao identificar esse termo, adote uma das duas táticas a seguir:
Se você alterar o nome de uma variável no meio de um método, seu código não será compilado. Da mesma forma, se você renomear um termo no meio de um documento, suas ideias não serão compiladas (na cabeça de seus usuários).
A moral: aplique a mesma palavra ou termo sem ambiguidade e de forma consistente em todo o seu documento. Depois de nomear um componente coisa, não o renomeie como treco. Por exemplo, o parágrafo a seguir renomeia erroneamente Buffers de Protocolo para protobufs:
Os Buffers de Protocolo têm sua própria linguagem de definição. Blá blá blá. E é por isso que os protobufs venceram tantas feiras municipais.
George Fairbanks, um engenheiro de software do Google, fez esta excelente observação sobre nomenclatura consistente:
Quando encontro duas palavras que parecem ser sinônimos, me pergunto se o autor está tentando sinalizar uma distinção sutil que preciso buscar e entender.
Sim, a redação técnica é cruel e restritiva, mas pelo menos a redação técnica oferece uma excelente solução alternativa. Ou seja, ao introduzir um nome de conceito ou nome de produto prolixo, você também pode especificar uma versão abreviada desse nome. Em seguida, você pode usar esse nome abreviado em todo o documento. Por exemplo, o parágrafo a seguir está bom:
Buffers de Protocolo (ou protobufs para abreviar) têm sua própria linguagem de definição. Blá blá blá. E é por isso que os protobufs venceram tantas feiras municipais.
No uso inicial de uma sigla desconhecida em um documento ou seção, descreva o termo completo e, em seguida, coloque a sigla entre parênteses. Coloque a versão por extenso e a sigla em negrito. Por exemplo:
Este documento é para engenheiros que são novos na Rede Tátil Telecinética (TTN) ou precisam entender como solicitar peças de reposição TTN por meio de movimentos dos dedos.
Você pode então usar a sigla daqui para frente, como no exemplo a seguir:
Se não existir nenhuma entrada de cache, o Mixer chama o OttoGroup Server (OGS) para buscar Ottos para a solicitação. O OGS é um repositório que contém todos os Ottos servíveis. O OGS está organizado em uma estrutura de árvore lógica, com um nó raiz e dois níveis de nós derivados. A raiz OGS encaminha a solicitação para as derivações e coleta as respostas.
Não alterne entre a sigla e a versão por extenso no mesmo documento.
Claro, você pode introduzir e usar siglas do jeito certo, mas você deve usar siglas? Bem, siglas reduzem o tamanho da frase. Por exemplo, TTN é duas palavras mais curta do que Rede Tátil Telecinética. No entanto, siglas são realmente apenas uma camada de abstração; os leitores devem expandir mentalmente as siglas recém aprendidas para o termo completo. Por exemplo, os leitores convertem TTN para Rede Tátil Telecinética em suas cabeças, então a sigla “mais curta” na verdade demora um pouco mais para ser processada do que o termo completo.
Siglas muito usadas criam a sua própria identidade. Após várias ocorrências, os leitores geralmente param de expandir as siglas para o termo completo. Muitos desenvolvedores da Web, por exemplo, esqueceram qual é a versão por extenso de HTML.
Aqui estão as diretrizes para siglas:
Corrija a seguinte passagem. Suponha que esta passagem seja a primeira menção ao termo MapReduce no documento e que MR seja a melhor abreviação.
Jeff Dean inventou o MapReduce em 1693, implementando o algoritmo em um computador baseado em silício fabricado com areia de praia, papel encerado, uma caneta e uma torradeira. Esta versão do MR bateu vários recordes mundiais de desempenho até 2014.
(Observe que a passagem anterior pretende ser humorística, não factual.)
Você pode tomar algumas abordagens diferentes aqui. Uma abordagem é associar a sigla MR ao termo completo e depois usar essa sigla:
Jeff Dean inventou o MapReduce (MR) em... Esta versão do MR bateu vários...
Alternativamente, você pode decidir que abreviar uma passagem tão curta sobrecarrega muito os leitores, então você simplesmente usará o termo MapReduce completo todas as vezes:
Jeff Dean inventou o MapReduce em... Esta versão do MapReduce bateu vários...
Aliás, um redator técnico mais experiente também converteria "areia de praia, papel encerado, uma caneta e uma torradeira" em uma lista com marcadores. Você aprenderá mais sobre isso na lição de Listas e Tabelas.
Muitos pronomes apontam para um substantivo previamente mencionado. Assim como acontece com ponteiros na programação, os pronomes tendem a causar alguns erros. Usar pronomes incorretamente causa o equivalente a um erro de ponteiro nulo (null pointer) na cabeça de seus leitores. Em muitos casos, você deve simplesmente evitar o pronome e reutilizar o substantivo. No entanto, a utilidade de um pronome às vezes supera seu risco (como nesta frase).
Considere as seguintes diretrizes de pronome:
Os seguintes pronomes causam mais confusão na documentação técnica:
Por exemplo, na frase a seguir, Ele se refere a Python ou a C++?
Python é interpretado, enquanto C++ é compilado. Ele tem um seguimento que é quase cult.
Como outro exemplo, a que se refere a palavra seu na frase a seguir?
Tenha cuidado ao usar Frambus ou Carambola com HoobyScooby ou BoiseFram, porque um bug em seu núcleo pode causar desamizamento em massa acidental.
Considere os seguintes pronomes também como problemáticos:
Por exemplo, na frase ambígua a seguir, Isso pode se referir ao ID do usuário, à execução do processo ou a todos eles:
A execução do processo configura permissões e gera um ID do usuário. Isso permite que os usuários se autentiquem no aplicativo.
Para ajudar os leitores, evite usar isso ou aquilo de forma que não esteja claro a que se referem. Use uma das seguintes táticas para esclarecer usos ambíguos de isso e aquilo:
Substitua ou adicione termos explícitos conforme necessário, como nas seguintes reescritas da segunda frase do exemplo:
Esse ID de usuário permite que os usuários se autentiquem.
O processo de configuração de permissões permite que os usuários se autentiquem.
A combinação de permissões e um ID de usuário permite que os usuários se autentiquem.
Identifique todos os significados possíveis para os pronomes ambíguos em cada uma das seguintes passagens:
Amanda e Felipe compartilham responsabilidades com Maísa e Carlos. Eles são os próximos de plantão.
Você pode importar os dados do Carambola através do seu arquivo de configuração ou dinamicamente em tempo de execução. Isso pode ser um risco de segurança.
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).