Redator técnico / engenheiro de documentação — tarefas, uma a uma

Redigir a referência

Esta é a tarefa de escrita mais exposta deste sítio, porque a fonte de verdade é legível por máquina e o formato de saída é fixo. Gerar uma tabela de parâmetros a partir de uma assinatura já era em parte automatizado pelos geradores de documentação muito antes dos modelos; o que os modelos acrescentaram foi prosa que se lê como se tivesse sido escrita por uma pessoa, e isso retirou a última razão para a escrever uma pessoa.

Uma referência gerada é uma referência que ninguém leu antes de publicar, e o modo de falha não é estar errada mas ser plausível: documentação que descreve aquilo que o código declara e não aquilo que ele faz. Essa distância só é encontrada por alguém a usar a coisa, que é a tarefa seguinte, por isso automatizar esta sobe o valor daquela em vez de retirar o posto.

Usar mesmo aquilo que estás a documentar

A entrada desta tarefa não existe em repositório nenhum: é a experiência de estar baralhado num sítio concreto. Um modelo treinado sobre o código herda o saber de quem o escreveu, que é precisamente o saber que tem de faltar para que o teste funcione: aqui o valor vem de não saber.

Esta tarefa é o argumento mais forte a favor da ocupação e o mais fraco numa reunião de orçamento, porque o que produz é uma ausência: os pedidos de suporte que não aconteceram. Onde as equipas de documentação foram cortadas, foi esta a tarefa que se foi primeiro, e para isso não foi precisa tecnologia nenhuma.

Decidir o que não se escreve

A geração barata torna esta a tarefa mais valiosa e não a menos, porque a restrição mudou de sítio: quando escrever tudo passou a ser possível, escolher passou a ser o posto inteiro. Decidir o que fica de fora depende de saber que utilizadores existem e o que estão a tentar fazer, e isso não está no código.

Ser mais valiosa não é o mesmo que ser reconhecida: a documentação é em geral medida por cobertura, e a cobertura é precisamente a métrica que a geração barata esvazia de sentido. Uma equipa julgada por páginas publicadas será premiada por abandonar esta tarefa exatamente no momento em que ela se torna a importante.

Arrancar a resposta a um engenheiro

A informação necessária está por documentar por definição: se estivesse escrita, esta tarefa não existia. Extraí-la é um ato social executado contra a agenda de alguém, e a competência está em saber que pergunta produz a resposta verdadeira e não a oficial.

Esta tarefa é o que torna difícil fazer este posto à distância, a tempo parcial ou da cadeira de um prestador externo, que é exatamente a direção para onde a pressão de custos empurra. A ameaça aqui não é a automatização, é o posto ser reestruturado em algo que não consegue incluir esta tarefa, depois do que a documentação se degrada por razões que ninguém atribui corretamente.