Em direção a uma teoria de qualidade em documentação

O Diátaxis é uma abordagem para a qualidade em documentação.

“Qualidade” é uma palavra em risco de perder parte do seu significado; é algo que todos nós aprovamos, mas que raramente nos arriscamos a tentar descrever de forma rigorosa. Queremos qualidade em nossa documentação, mas com muito menos frequência especificamos o que exatamente queremos dizer com isso.

Ainda assim, geralmente conseguimos apontar exemplos de “documentação de alta qualidade” quando solicitados, e podemos identificar falhas na qualidade quando as vemos - e, mais do que isso, frequentemente concordamos quando o fazemos. Isso sugere que ainda temos uma compreensão útil da noção de qualidade.

À medida que buscamos a qualidade na documentação, ajuda tornar essa compreensão mais segura, prestando atenção a ela - aqui, tentando refinar nossa compreensão ao propor uma distinção entre qualidade funcional e qualidade profunda.

Qualidade funcional

Precisamos que a documentação atenda a padrões de exatidão, completude, consistência, utilidade, precisão e assim por diante. Podemos chamar esses aspectos de sua qualidade funcional. Uma documentação que falha em atender a qualquer um deles está falhando em realizar uma de suas funções principais.

Essas propriedades da qualidade funcional são todas independentes umas das outras. A documentação pode ser exata sem ser completa. Pode ser completa, mas inexata e inconsistente. Pode ser exata, completa, consistente e também inútil.

Alcançar a qualidade funcional significa atender a padrões elevados e objetivamente mensuráveis em múltiplas dimensões independentes, de forma consistente. Isso exige disciplina, atenção aos detalhes e altos níveis de habilidade técnica.

Para tornar as coisas mais difíceis para o criador da documentação, qualquer falha em atender a todos esses padrões é prontamente aparente para o usuário.

Qualidade profunda

Existem outras características que podemos chamar de qualidade profunda.

A qualidade funcional não é suficiente, nem mesmo satisfatória por si só como ambição. A verdadeira excelência na documentação implica características de qualidade que não estão incluídas na exatidão, completude e assim por diante.

Pense em características como:

• ser agradável de usar

• ter fluidez

• adequar-se às necessidades humanas

• ser bonita

• antecipar-se ao usuário

Ao contrário das características da qualidade funcional, elas não podem ser verificadas ou medidas, mas ainda podem ser claramente identificadas. Quando as encontramos, geralmente (não sempre, porque precisamos ser capazes disso) as reconhecemos.

São características da qualidade profunda.

Qual é a diferença?

Aspectos da qualidade profunda parecem ser genuinamente distintos em natureza das características da qualidade funcional.

A documentação pode atender a todas as exigências da qualidade funcional e, mesmo assim, falhar em exibir a qualidade profunda. Existem muitos exemplos de documentação que é exata e consistente (e até mesmo muito útil), mas que também é desajeitada e desagradável de usar.

Também é perceptível que, enquanto as características da qualidade funcional, como completude e exatidão, são independentes umas das outras, as da qualidade profunda são difíceis de desemaranhar. Ter fluidez e antecipar-se ao usuário são aspectos um do outro - são interdependentes. É difícil ver como algo poderia ser agradável de usar sem se adequar às nossas necessidades.

Aspectos da qualidade funcional podem ser medidos - literalmente com números, em alguns casos (considere a completude). Isso claramente não é possível com qualidades como ter fluidez. Em vez disso, tais qualidades só podem ser questionadas, interrogadas. Em vez de obter medições, devemos fazer julgamentos.

A qualidade funcional é objetiva - pertence ao mundo. A exatidão da documentação significa a extensão em que ela se conforma ao mundo que está tentando descrever. A qualidade profunda não pode ser verificada comparando algo com o mundo. Ela é subjetiva, o que significa que podemos avaliá-la apenas à luz das necessidades do sujeito da experiência, o humano.

E a qualidade profunda é condicional à qualidade funcional. A documentação pode ser exata, completa e consistente sem ser verdadeiramente excelente - mas nunca terá qualidade profunda sem ser exata, completa e consistente. Nenhum usuário da documentação a experimentará como bela se ela for inexata, ou desfrutará da maneira como ela se antecipa às suas necessidades se ela for inconsistente. No momento em que nos deparamos com tais falhas, a experiência da documentação é manchada.

Finalmente, todas as características da qualidade funcional nos parecem, como criadores de documentação, como fardos e restrições. Cada uma delas representa um teste ou desafio no qual podemos falhar. Ou, mesmo que tenham atendido a uma delas agora, nunca podemos descansar, porque a próxima versão ou atualização significa que teremos que verificar nosso trabalho mais uma vez, em relação àquilo que ele está documentando. Características como antecipação de necessidades ou fluidez, por outro lado, representam libertação, o trabalho da criatividade ou do gosto. Para alcançar a qualidade funcional em nosso trabalho, devemos nos conformar a restrições; para alcançar a qualidade profunda, devemos inventar.

Qualidade funcional	Qualidade profunda
características independentes	características interdependentes
objetiva	subjetiva
medida contra o mundo	avaliada em relação ao humano
condição da qualidade profunda	condicional à qualidade funcional
aspectos de restrição	aspectos de libertação

Como reconhecemos a qualidade profunda

Considere como julgamos a qualidade de, digamos, roupas. As roupas devem ter qualidade funcional (devem nos manter adequadamente aquecidos e secos, resistir ao desgaste). Essas coisas são objetivamente mensuráveis. Você realmente não precisa saber muito sobre roupas para avaliar o quão bem elas cumprem essas funções. Se a água entrar ou a roupa se rasgar - ela carece de qualidade.

Existem outras características de qualidade nas roupas que não podem ser medidas de forma puramente objetiva e, para reconhecer essas características, precisamos ter uma compreensão sobre vestuário. A qualidade dos materiais ou do acabamento nem sempre é imediatamente óbvia. Ser capaz de julgar se uma peça de roupa tem um bom caimento, se move bem ou foi moldada com maestria exige desenvolver, pelo menos, um olhar básico para essas coisas. E essas são as suas características de qualidade profunda.

Mas: mesmo alguém que não consegue reconhecer, ou não entende, essas características - que não sabe dizer quais são elas - ainda pode reconhecer muito bem que a roupa é excelente, porque percebe que ela é agradável de vestir, porque é algo que ela quer usar. Nenhuma especialidade é necessária para perceber que uma roupa é ou não confortável enquanto você se move, que ela se ajusta e se move bem com você. Seu corpo sabe disso.

E é o mesmo na documentação. Talvez você precise ser um especialista para reconhecer o que torna uma documentação excelente, mas isso não é necessário para conseguir perceber que ela é excelente. Uma boa documentação dá uma sensação boa; você sente prazer e satisfação ao usá-la - parece que ela se ajusta e se move com você.

Os usuários da nossa documentação podem ou não ter o entendimento para dizer por que ela é boa, ou onde sua qualidade falha. Eles podem reconhecer apenas os aspectos mais óbvios da qualidade funcional nela, confundindo-os com sua excelência mais profunda. Isso não importa - ela será agradável de usar, ou não, e é isso que é importante.

Mas nós, como seus criadores, precisamos de uma compreensão clara e eficaz do que torna a documentação boa. Precisamos desenvolver nossa percepção dela para que reconheçamos o que há de bom nela, bem como que ela é boa. E precisamos desenvolver uma compreensão de como as pessoas vão se sentir ao usá-la.

Produzir um trabalho de qualidade profunda depende da nossa habilidade de fazer isso.

Diátaxis e qualidade

As obrigações da qualidade funcional são cumpridas através da observância cuidadosa das demandas do ofício de documentação. Elas exigem habilidade sólida e conhecimento do domínio técnico, a capacidade de reunir um terreno completo em um único mapa coerente e consistente dele.

O Diátaxis não pode tratar da qualidade funcional na documentação. Ele se preocupa apenas com certos aspectos da qualidade profunda, alguns mais do que outros - embora, se todos os aspectos da qualidade profunda estiverem emaranhados uns nos outros, isso afetará a todos eles.

Expondo falhas na qualidade funcional

Embora o Diátaxis não possa tratar ou nos fornecer a qualidade funcional, ele ainda pode servir a ela.

Ele funciona de forma muito eficaz para expor falhas na qualidade funcional. Costuma-se notar que um efeito da aplicação do Diátaxis à documentação existente é que problemas que antes estavam ocultos de repente tornam-se aparentes.

Por exemplo: a abordagem Diátaxis recomenda que a arquitetura da\ documentação de referência deve refletir a arquitetura do código que ela documenta. Isso torna as lacunas na documentação muito mais visíveis.

Ou mover o palavreado explicativo para fora de um tutorial (de acordo com as demandas do Diátaxis) geralmente tem o efeito de destacar uma seção onde o leitor foi deixado para descobrir algo por conta própria.

Mas, no que diz respeito à qualidade funcional, os princípios do Diátaxis só podem ter um papel analítico.

Criando qualidade profunda

Por outro lado, na qualidade profunda, a abordagem Diátaxis pode fazer mais.

Por exemplo, ela ajuda a documentação a se adequar às necessidades do usuário descrevendo modos de documentação baseados nelas; suas categorias existem como uma resposta às necessidades.

Devemos prestar atenção, portanto, à organização correta dessas categorias, ao arranjo de seu material e às relações dentro delas, bem como à forma e linguagem adotadas em diferentes partes da documentação - como uma forma de se ajustar às necessidades do usuário.

Ou, no Diátaxis, estamos diretamente preocupados com a fluidez. Na fluidez - seja no contexto da documentação ou de qualquer outra coisa - experimentamos um movimento de um estágio ou estado para outro que parece correto, natural e em harmonia tanto com nossas preocupações do momento quanto com a maneira como nossas mentes e corpos funcionam em geral.

O Diátaxis preserva a fluidez ajudando a evitar o tipo de interrupção de ritmo que ocorre quando algo vai contra nosso propósito e progresso constante em direção a ele (for exemplo, quando uma digressão para explicação interrompe um guia de como fazer).

E assim por diante.

Entendendo os limites

É importante entender que o Diátaxis nunca pode ser tudo o que é necessário na busca pela qualidade profunda.

Por exemplo, embora ele possa ajudar a alcançar a beleza na documentação, pelo menos em sua forma geral, ele não torna, por si só, a documentação bonita.

O Diátaxis oferece um conjunto de princípios - ele não oferece uma fórmula. Ele certamente não pode oferecer um atalho para o sucesso, ignorando as habilidades e percepções de disciplinas como experiência do usuário (UX), design de interação ou até mesmo design visual.

Usar o Diátaxis não garante qualidade profunda. As características da qualidade profunda estão sempre sendo renegociadas, reinterpretadas, redescobertas e reinventadas. Mas o que o Diátaxis can fazer é estabelecer algumas condições para a possibilidade de qualidade profunda na documentação.