Introdução

Acho que todos os redatores técnicos, mais cedo ou mais tarde, sentem a necessidade de basear o seu trabalho em algo mais sistemático do que “é simplesmente assim que as pessoas documentam as coisas desde sempre”. Os conjuntos de ferramentas e os frameworks oferecem tipos de conteúdo, o que tem um valor imenso quando você sabe o que quer escrever; mas começar por aí é como comprar um martelo sem saber que metade do trabalho será apertar parafusos.

Frameworks, ferramentas e formatos de documentação não são suficientes

A maioria dos frameworks de documentação existentes se concentra nas ações dos redatores técnicos em vez de se concentrar nas ações dos usuários, isto é, dos consumidores da documentação. A ênfase prescritiva sobre os documentos que devem ser produzidos, em vez de descrever as necessidades dos usuários que se deve atender, lembra uma mentalidade arquitetônica em que se levantam paredes porque é claro que uma casa tem de ter cômodos, o que somos nós, bárbaros? Essa aparente falta de flexibilidade desestimula a escrita do conteúdo realmente necessário.

Algumas das pessoas que conceberam frameworks de documentação têm consciência desse problema e sugeriram que as suas regras não devem ser seguidas ao pé da letra e que há espaço para flexibilidade na aplicação ao mundo real. Os redatores que usam esses frameworks também enfrentaram esse dilema e, na maioria dos casos, acabaram adaptando-os aos seus contextos. Os frameworks se tornam assim conjuntos de ferramentas dos quais se escolhem templates e ideias. Esse padrão, porém, contorna a pergunta sobre o que é realmente necessário.

Diante da complexidade de documentar produtos em rápida evolução com poucos recursos e pouco suporte, os redatores aproveitam tudo o que conseguem e constroem com isso um processo funcional. Por outro lado, os engenheiros que começam a experimentar a documentação e se sentem perdidos ao se aproximar da área são atraídos pelos frameworks, porque é a única forma de trabalhar a que estão acostumados na programação. A documentação que acabam desenvolvendo é uma versão de culto à carga de uma documentação eficaz.

Mudar o foco dos tipos de conteúdo para as necessidades dos usuários

Uma solução para essa situação é mudar o foco daquilo que deve ser escrito para as necessidades dos usuários que se deve atender. Isso exige assumir a responsabilidade pelo lado estratégico da documentação — no sentido de estratégia de conteúdo — em vez de produzir conteúdo segundo padrões estruturais predefinidos. Essa abordagem é totalmente compatível com frameworks de documentação como o Diátaxis, o DITA e outros, porque dá direção e propósito a quem constrói a documentação, que poderá então usar os tipos de conteúdo, os elementos e as ferramentas à sua disposição.

A forma como, na minha opinião, os frameworks, as ferramentas e os modelos mentais das necessidades dos usuários se articulam pode ser compreendida pela metáfora de um sanduíche, sobretudo se você ainda não almoçou: os frameworks e as ferramentas de documentação são ingredientes essenciais para manter o sanduíche inteiro e permitir que ele seja segurado, mas o que lhe dá todo o sabor e significado é o recheio, isto é, o modelo mental das necessidades dos usuários que você segue. Isso não é o mesmo que os pedidos externos das partes interessadas, embora possam se sobrepor. Quando muito, os OKRs são o molho.

Em outras palavras, para construir documentação eficaz não bastam ferramentas e tipos de conteúdo: é preciso também um modelo das necessidades que a documentação deve satisfazer enquanto produto, ou das ações que os usuários devem conseguir realizar por meio dela. Esse modelo deve ser relativamente independente do tipo de produto de software documentado, da mesma forma que os modelos conceituais de concepção e satisfação de produto abstraem os detalhes específicos. Buscar um modelo geral é necessário porque ajuda os profissionais a aprender e a se comunicar entre si.

O que se segue é o meu próprio modelo descritivo das necessidades dos usuários de documentação, aquele que uso atualmente para construir e organizar documentação.

O modelo de documentação de sete ações

A abordagem que proponho é um modelo das ações dos usuários que a documentação deve atender. O modelo procura ligar a pesquisa de UX e os frameworks de documentação por uma camada conceitual e funcional centrada em dois aspectos: a documentação como produto e o que os usuários devem conseguir fazer por meio dela. É uma tentativa de descrever o que a documentação técnica deve fazer. É tratar a documentação como um produto que alguém vai usar para alcançar objetivos reais.

Como falei, o núcleo do modelo são as ações. Identifiquei sete que, na minha opinião, abrangem boa parte dos objetivos que um consumidor de documentação pode querer alcançar ao usá-la. Elas representam padrões comuns na forma como os usuários interagem com a documentação em diferentes produtos e domínios. São as seguintes, cada uma acompanhada de um termo alternativo entre parênteses: Avaliar (Discernir), Compreender (Aprender), Explorar (Descobrir), Praticar (Treinar), Recordar (Relembrar), Desenvolver (Integrar) e Resolver (Solucionar).

Note que a ordem das ações é intencional, mas não rígida: organizei-as numa sequência que se aproxima do que considero ser a abordagem dos consumidores à documentação técnica de software. Vejo essas ações acontecendo em fases ou níveis diferentes. Quando dispostas num heptágono regular, as ações do topo tendem a ocorrer nas fases iniciais da interação com o produto, ao passo que as da parte de baixo acontecem quando o conhecimento e o uso do produto já se consolidaram.

Conclusão

O modelo que apresento aqui oferece uma forma de pensar a documentação pela ótica das necessidades dos usuários, em vez dos tipos de conteúdo. Ele não pretende substituir os frameworks existentes, e sim complementá-los. Usados em conjunto, permitem aos redatores técnicos criar documentação que seja estruturalmente sólida e sirva a propósitos reais, em vez de apenas preencher templates.

O modelo também pode servir de base para métricas e definição de objetivos da documentação (do11y). Em vez de olhar apenas para as visualizações de páginas ou as notas de satisfação, as equipes podem acompanhar até que ponto a sua documentação serve a cada ação. Por exemplo, as taxas de conversão da documentação para a adoção do produto podem medir a eficácia da avaliação, enquanto as métricas de tempo de resolução podem indicar o sucesso da resolução de problemas.

Como acontece com os modelos teóricos, este não é sustentado por pesquisa extensa nem por análise fatorial. O modelo é distribuído COMO ESTÁ e, em hipótese alguma, você poderá me responsabilizar por ter estragado o seu almoço. Espero, ainda assim, que ofereça uma perspectiva útil aos redatores técnicos que buscam criar documentação com um propósito mais claro.