Introdução

Penso que todos os Technical Writers, 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 as frameworks categorizam tipos de conteúdo, facto que tem um valor imenso quando se sabe o que se quer escrever. No entanto, 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 das frameworks de documentação existentes concentra-se nas ações dos Technical Writers em vez de se concentrar nas ações dos utilizadores, isto é, dos consumidores da documentação. A ênfase prescritiva sobre os documentos que devem ser produzidos, em vez de descrever as necessidades dos utilizadores a que se deve responder, faz lembrar uma mentalidade arquitetónica em que se constroem paredes porque é evidente que uma casa tem de ter divisões, o que somos nós, bárbaros? Esta aparente falta de flexibilidade desencoraja a escrita dos conteúdos realmente necessários.

Algumas das pessoas que conceberam frameworks de documentação estão conscientes deste problema e sugeriram que as suas regras não deviam ser seguidas à letra e que há flexibilidade na sua aplicação ao mundo real. Aqueles que utilizam essas frameworks também enfrentaram este dilema e, na maioria dos casos, acabaram por adaptá-las aos seus contextos. As frameworks tornam-se assim conjuntos de ferramentas das quais se escolhem estruturas e ideias. Este padrão, porém, evita a pergunta sobre o que é realmente necessário.

Perante a complexidade de documentar produtos em rápida evolução com poucos recursos e pouco apoio, os Technical Writers aproveitam tudo o que conseguem e constroem com isso um processo funcional. Por outro lado, os engenheiros que começam a documentar sentem-se perdidos, e, ao aproximarem-se da área, são atraídos pelas frameworks, porque é a forma habitual de trabalhar em programação. A documentação que acabam por desenvolver é uma versão de culto de uma documentação eficaz.

Mudar o foco dos tipos de conteúdo para as necessidades dos utilizadores

Uma solução para esta situação é mudar o foco daquilo que deve ser escrito para as necessidades dos utilizadores às que se deve dar resposta. Esta mudança exige assumir a responsabilidade pelo lado estratégico da documentação (no sentido de estratégia de conteúdo) em vez de produzir conteúdos segundo padrões estruturais predefinidos. Esta abordagem é totalmente compatível com frameworks de documentação como a Diátaxis, DITA e outras, porque dá direção e propósito a quem constrói a documentação, que pode então usar os tipos de conteúdo, os elementos e as ferramentas ao seu dispor.

A forma como, na minha opinião, as frameworks, as ferramentas e os modelos mentais das necessidades dos utilizadores se articulam pode ser compreendida através de uma metáfora de uma sanduíche, sobretudo quando ainda não se almoçou: as frameworks e as ferramentas de documentação são ingredientes essenciais para manter a sanduíche inteira e permitir que seja manuseada, mas aquilo que lhe dá todo o sabor e significado é o recheio, isto é, o modelo mental das necessidades dos utilizadores que se segue. Isto não é o mesmo que os pedidos externos das partes interessadas, embora possam sobrepor-se. Quando muito, os OKR são o molho.

Por outras palavras, para construir documentação eficaz não são apenas necessárias ferramentas e tipos de conteúdo, mas também um modelo das necessidades que a documentação deve satisfazer enquanto produto, ou das ações que os utilizadores devem conseguir realizar através dela. Este modelo deve ser relativamente independente do tipo de produto de software documentado, da mesma forma que os modelos conceptuais de design e satisfação de produto abstraem os pormenores específicos. Procurar um modelo geral torna-se necessário porque ajuda os profissionais a aprender e a comunicar entre si.

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

O modelo de documentação 7-Ações

A abordagem que proponho é um modelo das ações dos utilizadores às quais a documentação se destina a responder. O modelo procura ligar a investigação de UX e as frameworks de documentação através de uma camada conceptual e funcional centrada em dois aspetos: a documentação como produto e aquilo que os utilizadores devem conseguir fazer através 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 utilizar para alcançar objetivos reais.

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

Note-se que a ordem das ações é intencional, mas não rígida: organizei-as numa sequência que se assemelha àquilo que considero ser a abordagem dos consumidores à documentação técnica de software. Vejo estas ações a acontecer em diferentes fases ou níveis. 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 inferior acontecem quando o conhecimento e a utilização do produto já se consolidaram.

Conclusão

O modelo que apresento aqui oferece uma forma de pensar a documentação através das necessidades dos utilizadores, em vez dos tipos de conteúdo. Não pretende substituir as frameworks existentes, mas complementá-las. Utilizados em conjunto, permitem aos technical writers criar documentação estruturalmente sólida e que serve propósitos reais, em vez de se limitar a preencher estruturas predefinidas.

O modelo também pode servir de base para métricas e definição de objetivos da documentação (do11y). Em vez de se concentrarem apenas nas visualizações de páginas ou nas pontuações de satisfação, as equipas podem acompanhar até que ponto a sua documentação serve 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 êxito da resolução de problemas.

Como acontece com os modelos teóricos, o presente modelo não é sustentado por investigação extensa nem por análise fatorial. O modelo é distribuído TAL COMO ESTÁ e, em circunstância alguma, alguém poderá responsabilizar-me por lhe ter estragado o almoço. Ainda assim, espero que ofereça uma perspetiva útil a todos os Technical Writers que procuram criar documentação com um propósito mais claro.