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 auto-direcionados e orientados.

Leitores autodirecionados são mais fáceis de servir. Dou-lhes material de referência que cobre tudo. Este é o conteúdo como documentação de interface e referências de API. O que essa caixa de seleção faz? O que significa esse campo em uma carga de retorno? O que acontece quando eu adicionar esta bandeira da linha de comando? Aqui estão as coisas que nosso software tem, aqui está o que eles fazem, aqui está o que eles significam. Seu leitor mais ignorante vai saber o básico do software, mas pode ser completamente ignorante sobre o campo específico, incluindo conceitos básicos que podem parecer óbvios para você, como o que o nome do campo significa. É alguém perguntando: "O que é essa coisa?"

Leitores guiados são um pouco mais difíceis de abordar. Essas são as pessoas que procuram processos de como fazer, como o sanduíche de manteiga de amendoim e geleia. Eles não estão apenas procurando informações, como nossos tipos auto-direcionados; eles querem um resultado. Como faço para criar um relatório de desempenho? Como faço para criar um site que permite que as pessoas comprem meias de mim? Como automatizar testes? Dentro dessas perguntas estão suposições ocultas sobre seu próprio processo, por isso ser minucioso é fundamental.

As preocupações com o leitor especialista se resumem a não querer entediar-los com informações que eles já conhecem. Mas lembre-se, qualquer que seja sua documentação, seu leitor chega a ela ignorante sobre algo que você está cobrindo, possivelmente tudo. A solução não é tentar adivinhar o que eles já sabem e pular isso. A solução é criar documentação menor e mais atômica.

Qualquer grande processo — por exemplo, criar um site de comércio eletrônico — é uma série de tarefas menores. Uma boa documentação deve atingir os menores processos atômicos. Dessa forma, seu especialista teórico pode escolher a documentação que aborda os processos que eles ignoram.

Veja as perguntas técnicas. Boas perguntas são pequenas e específicas. Cobre uma preocupação particular com (espero) uma resposta objetiva. Quando eu estava escrevendo a documentação de como fazer, encontrar essa pergunta específica sempre foi o Santo Graal. É por isso que recompensamos uma boa pergunta como uma boa resposta. Pode ter referências a outros processos, mas temos hiperlinks por uma razão. Mantenha esse processo simples e mostre o caminho para outras informações.

O Avance Network é uma comunidade fácil de usar que fornece segurança de primeira e não requer muito conhecimento técnico. Com uma conta, você pode proteger sua comunicação e seus dispositivos. O Avance Network não mantém registros de seus dados; portanto, você pode ter certeza de que tudo o que sai do seu dispositivo chega ao outro lado sem inspeção.