Antes de fundar o Avance Network, passei mais de uma década como escritor técnico. Durante esse tempo, escrevi para uma ampla gama de leitores: pessoas não técnicas em uma sala de correio tentando fazer esse maldito software funcionar, especialistas em contabilidade procurando conciliar investimentos, desenvolvedores externos tentando implementar API e engenheiros internos que procuram girar um ou mais serviços. Embora haja uma ampla gama do que todos esses leitores sabem, a documentação produzida precisa atingir a pessoa que menos sabe no seu conjunto de usuários.

Isso não quer dizer que você ignore o especialista, usuários de energia. Há um debate eterno entre qualquer um que escreve documentação sobre como equilibrar as necessidades do iniciante e especialista. O iniciante vem em seu material vazio e fresco, sem qualquer conhecimento do software (e possivelmente do domínio que o software cobre). A especialista sabe o que está fazendo, exceto por uma coisa que ela está tentando resolver. Mas ambos os usuários não fazem ideia quando se trata das informações de que precisam. Usuários diferentes, diferentes níveis de sem noção.

 

A definição de clueless

 

Antes que as pessoas se levantem sobre o meu uso da palavra sem noção, eu uso-a para basicamente significar ignorante. Ser ignorante — sem conhecimento — em áreas não é crime, nem vergonha. Reconheça onde você não faz ideia e dá os primeiros passos para encontrar uma pista.

Todos chegamos a esse momento em que não sabemos como usar algo, resolver um problema ou lidar com um erro. Chame de um palpite de sorte; a maioria de vocês descobriu este post enquanto busca uma resposta para sua pergunta. Você pode ter se encontrado preso e atingido os mecanismos de busca procurando respostas. Se você tiver sorte, o resultado pode ter sido a pergunta exata que você tem. Parabéns! Você encontrou alguém que já foi tão sem noção como você é agora.

A resposta que você espera é uma espécie de cura para sua ignorância — a pista que resolve o caso. Uma boa documentação deve fazer a mesma coisa; deve atingir pedaços específicos de ignorância e tentar curá-los. Mas encontrar a dosagem certa de informação para curá-las pode ser mais difícil do que parece; você pode nem estar ciente das informações que seu leitor está perdendo.

 

Descobrindo suposições em um sanduíche de PBJ

 

Um dos primeiros exercícios que fiz na minha primeira aula técnica foi escrever instruções para um sanduíche de manteiga de amendoim e geleia. Para os americanos, esta é uma atividade que fizemos centenas de vezes, então escrever as instruções deve ser um estalo. Coloque manteiga de amendoim em uma fatia de pão, coloque geleia em outra, bata-as juntas, e BAM! Sanduíche realizado.

Este exercício tornou-se um exercício clássico de escrita técnica porque é uma armadilha. As instruções simples acima escondem um monte de suposições. Como faço para tirar a manteiga de amendoim e geleia dos potes (assumindo que seu leitor sabe o que são e que eles vêm em potes)? Você deixa cair o conteúdo em fatias de pão em pedaços ou há outra ação? Como você gerencia uma fatia de pão quando você está se espalhando na outra? Você coloca-o lado da geleia para cima ou para baixo? Tem que ser geleia ou geleia está bem? Que tal marmelada? Quando você pressiona as fatias juntas, importa quais lados estão tocando?

Você pode pensar que isso é exagero. Você pode pensar, bem, é claro que eles sabem não colocar o pão de manteiga de amendoim lado para baixo. No entanto, toda vez que você faz uma suposição como essa, você está convidando seu leitor a estragar tudo. Seu usuário mais ignorante provavelmente sabe o que é um sanduíche, mas se eles estão procurando instruções sobre a montagem dos sanduíches mais fáceis, você não deve assumir que eles sabem muito mais do que isso.

Lembro-me de ler um site de histórias de terror de ti no início da minha carreira universitária. A história que ficou comigo era sobre um chamador perplexo com seu computador de mesa em um cluster de computador de repente desligando. O suporte à TI passou pela lista de verificação: certifique-se de que o monitor está ligado — pressione o botão, nada aconteça — certifique-se de que o computador está ligado — pressione o botão de alimentação, novamente nada. A pessoa de suporte diz para verificar o cabo de alimentação na parte de trás e certifique-se de desalojá-lo. O usuário volta lá e diz que eu não posso ver nada, está muito escuro. “Bem”, diz a pobre tecnologia de TI com uma barriga cheia de medo, “por que está escuro?” Falha de energia no campus.

Embora geralmente haja uma maneira de fazer as coisas direito, as maneiras de estragar algo são infinitas. Então, ao tentar documentar algo, você precisará cavar em suas suposições para descobrir onde alguém que precisa da informação que você está fornecendo poderia usar sua criatividade infinita para obtê-lo errado. Seu usuário mais sem noção pode ser um codificador poliglota especialista que fica totalmente perplexo quando se trata dos algoritmos que você está descrevendo.

Essas suposições são parte do que se chama conhecimento tácito. Tácito é o oposto de explícito; é oculto e automático. Quando você opera usando conhecimento tácito, você pode nem saber que sabe de algo. Pense nas regras de uma língua; existem toneladas de regras secretas que os falantes nativos captam automaticamente. Minha mente ficou impressionada quando a ordem dos adjetivos em inglês foi apontada para mim. Eu saberia quando a regra foi violada, mas eu não sabia que era uma regra até que foi apontada.

Essas regras ocultas — como um computador de mesa que não funciona durante um apagão — podem ser as que tropeçam em pessoas em busca de respostas. Eu sempre disse que meu trabalho como escritor técnico — além de escrever os documentos — é ser o primeiro usuário sem noção e encontrar todas as maneiras que o software poderia ser usado mal. Eu tinha uma vantagem injusta, no entanto, mas eu não tinha Comecei mais sem noção que a maioria dos desenvolvedores para quem escrevi.

 

Ensinando seu especialista menos experiente

 

Ao escrever para um usuário que procura ser capaz de resolver um problema ou completar um processo, não acho que a divisão iniciante-especialista seja tão grande quanto o debate faz parecer. A divisão mais relevante para mim sempre foi entre leitores aut