Em direção a uma teoria da qualidade na documentação

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

“Qualidade” é uma palavra em risco de perder parte do seu significado; é algo que todos aprovamos, mas que raramente arriscamos 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 conseguimos identificar falhas de 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 firme, prestando-lhe alguma atenção — aqui, tentando refinar nossa compreensão ao postular uma distinção entre qualidade funcional e qualidade profunda.

Qualidade funcional

Precisamos que a documentação atenda a padrões de precisão, integridade, consistência, utilidade, pontualidade e assim por diante. Podemos chamar esses aspectos de sua qualidade funcional. A documentação que falha em atender a qualquer um deles deixa de cumprir uma de suas funções principais.

Essas propriedades da qualidade funcional são todas independentes entre si. A documentação pode ser precisa sem ser completa. Pode ser completa, mas imprecisa e inconsistente. Pode ser precisa, completa, consistente e também inútil.

Atingir a qualidade funcional significa atender a padrões altos 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 dificultar 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 precisão, integridade e assim por diante.

Pense em características como:

• sensação agradável ao usar

• fluidez

• adequação às necessidades humanas

• beleza

• antecipação ao usuário

Ao contrário das características de qualidade funcional, elas não podem ser verificadas ou medidas, mas ainda assim podem ser claramente identificadas. Quando nos deparamos com elas, geralmente (nem sempre, pois precisamos ser capazes disso) as reconhecemos.

Elas são características da qualidade profunda.

Qual é a diferença?

Os aspectos da qualidade profunda parecem ser genuinamente distintos em espécie das características da qualidade funcional.

A documentação pode atender a todas as demandas de qualidade funcional e ainda assim falhar em exibir qualidade profunda. Existem muitos exemplos de documentação que é precisa e consistente (e até muito útil), mas que também é incômoda e desagradável de usar.

Também é perceptível que, enquanto características de qualidade funcional como integridade e precisão são independentes entre si, as de qualidade profunda são difíceis de desatar. Fluidez e antecipação ao usuário são aspectos uma da outra — elas 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 integridade). Isso claramente não é possível com qualidades como fluidez. Em vez disso, tais qualidades só podem ser investigadas e interrogadas. Em vez de fazer medições, devemos fazer julgamentos.

A qualidade funcional é objetiva — pertence ao mundo. A precisão da documentação significa o grau 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 só podemos avaliá-la à luz das necessidades do sujeito da experiência, o ser humano.

E a qualidade profunda é condicional em relação à qualidade funcional. A documentação pode ser precisa, completa e consistente sem ser verdadeiramente excelente — mas nunca terá qualidade profunda sem ser precisa, completa e consistente. Nenhum usuário da documentação a experimentará como bela se for imprecisa, nem apreciará a forma como ela antecipa suas necessidades se 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 tenhamos atendido a um agora, nunca podemos descansar, porque o próximo lançamento 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 atingir a qualidade funcional em nosso trabalho, devemos nos conformar às restrições; para atingir a qualidade profunda, devemos inventar.

Qualidade funcional	Qualidade profunda
características independentes	características interdependentes
objetiva	subjetiva
medida em relação ao mundo	avaliada em relação ao ser humano
uma 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, e resistir ao uso). Essas coisas são objetivamente mensuráveis. Você realmente não precisa saber muito sobre roupas para avaliar quão bem elas cumprem essas funções. Se a água entrar ou a roupa se desmanchar, falta-lhe qualidade.

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

Mas: mesmo alguém que não consegue reconhecer ou deixa de entender essas características — que não sabe dizer quais elas são — ainda pode reconhecer muito bem que a roupa é excelente, porque acha que é agradável de vestir, porque é tal que as pessoas querem usá-la. Nenhuma perícia é necessária para perceber que uma roupa é ou não confortável enquanto você se move nela, ou que ela se ajusta e se move bem com você. Seu corpo sabe disso.

E o mesmo acontece na documentação. Talvez seja preciso ser um conhecedor para reconhecer o que torna alguma documentação excelente, mas isso não é necessário para ser capaz de perceber que ela é excelente. Uma boa documentação tem uma sensação agradável; 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 a compreensão para dizer por que ela é boa, ou onde estão suas falhas de qualidade. 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 nosso senso a respeito para reconhecer o que há de bom nela, bem como que ela é boa. E precisamos desenvolver a compreensão de como as pessoas se sentirão ao usá-la.

Produzir trabalho de qualidade profunda depende de nossa capacidade de fazer isso.

Diátaxis e qualidade

As obrigações da qualidade funcional são cumpridas por meio da observância conscienciosa 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 mapa único, coeso e consistente dele.

O Diátaxis não pode abordar a 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, ele afete a todos eles.

Expondo falhas na qualidade funcional

Embora o Diátaxis não possa abordar ou fornecer qualidade funcional, ele ainda pode servi-la.

Ele funciona de forma muito eficaz para expor falhas na qualidade funcional. É frequentemente observado que um efeito de aplicar o Diátaxis à documentação existente é que problemas nela se tornam repentinamente aparentes, antes obscurecidos.

Por exemplo: a abordagem do 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, remover o texto explicativo de um tutorial (de acordo com as exigências do Diátaxis) frequentemente tem o efeito de destacar uma seção onde o leitor foi deixado para resolver algo por conta própria.

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

Criando qualidade profunda

Na qualidade profunda, por outro lado, a abordagem do Diátaxis pode fazer mais.

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

Devemos, portanto, prestar atenção à organização correta dessas categorias, à disposição de seu material e às relações dentro deles, à forma e à linguagem adotadas em diferentes partes da documentação — como uma forma de nos adequarmos às necessidades do usuário.

Ou, no Diátaxis, lidamos diretamente com a fluidez. Na fluidez — seja o contexto a documentação ou qualquer outra coisa —, experimentamos um movimento de um estágio ou estado para outro que parece correto, sem esforço e em sintonia tanto com nossas preocupações do momento quanto com a forma como nossas mentes e corpos funcionam em geral.

O Diátaxis preserva a fluidez ajudando a prevenir o tipo de interrupção de ritmo que ocorre quando algo colide com nosso propósito e com o progresso constante em direção a ele (por exemplo, quando uma digressão explicativa interrompe um guia de instruções).

E assim por diante.

Compreendendo os limites

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

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

O Diátaxis oferece um conjunto de princípios — ele não oferece uma fórmula. Certamente ele não pode oferecer um atalho para o sucesso, contornando as habilidades e percepções de disciplinas como experiência do usuário, design de interação do usuário ou mesmo design visual.

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