Diátaxis em hierarquias complexas

Estrutura do conteúdo da documentação

A aplicação do Diátaxis na maioria das documentações é bastante direta. O produto que define o domínio de interesse possui limites claros, e é possível propor um arranjo de conteúdos de documentação que se pareça - por exemplo - com isto:

Início                    <- página de destino
    Tutorial              <- página de destino
        Parte 1
        Parte 2
        Parte 3
    Guias de como fazer   <- página de destino
        Instalar
        Implantar
        Escalar
    Referência            <- página de destino
        Ferramenta de linha de comando
        Endpoints disponíveis
        API
    Explicação            <- página de destino
        Recomendações de boas práticas
        Visão geral de segurança
        Desempenho

Em cada caso, uma página de destino contém uma visão geral do conteúdo nela contido. O tutorial, por exemplo, descreve o que o tutorial tem a oferecer, fornecendo contexto para ele.

Adicionando uma camada de hierarquia

Mesmo conjuntos de documentação muito grandes podem usar isso de forma eficaz, embora, depois de um tempo, possa ser aconselhável agrupar o conteúdo em seções. Isso pode ser feito adicionando outra camada de hierarquia - por exemplo, para poder abordar diferentes opções de instalação separadamente:

Início                    <- página de destino
    Tutorial              <- página de destino
        Parte 1
        Parte 2
        Parte 3
    Guias de como fazer   <- página de destino
        Instalar           <- página de destino
            Instalação local
            Docker
            Máquina virtual
            Contêiner Linux
        Implantar
        Escalar
    Referência            <- página de destino
        Ferramenta de linha de comando
        Endpoints disponíveis
        API
    Explicação            <- página de destino
        Recomendações de boas práticas
        Visão geral de segurança
        Desempenho

Páginas de conteúdo

Páginas de conteúdo - normalmente uma página inicial e quaisquer páginas de destino - fornecem uma visão geral do material que abrangem.

Existe uma arte em criar uma boa página de conteúdo. A experiência que elas proporcionam aos usuários merece consideração cuidadosa.

O problema das listas

Listas com mais de alguns itens são muito difíceis de ler para os humanos, a menos que tenham uma ordem mecânica inerente - numérica ou alfabética. Sete itens parecem ser um limite geral confortável. Se você perceber que está olhando para listas mais longas que isso em seus sumários, provavelmente precisará encontrar uma maneira de dividi-las em listas menores.

Como sempre, o que mais importa é a experiência do leitor. O Diátaxis funciona porque atende bem às necessidades do usuário - se a sua execução do Diátaxis levar a formatos que pareçam desconfortáveis ou feios, você precisará usá-lo de forma diferente.

Visões gerais e textos introdutórios

O próprio conteúdo de uma página de destino deve ser lido como uma visão geral.

Ou seja, ela não deve simplesmente apresentar listas de outros conteúdos, deve apresentá-los. Lembre-se de que você está sempre escrevendo para um usuário humano, não cumprindo as exigências de um esquema.

Cabeçalhos e trechos de texto introdutório chamam a atenção e fornecem contexto; por exemplo, uma página de destino de como fazer:

Guias de como fazer
===================

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Guias de instalação
-------------------

Pellentesque malesuada, ipsum ac mollis pellentesque, risus
nunc ornare odio, et imperdiet dui mi et dui. Phasellus vel
porta turpis. In feugiat ultricies ipsum.

* Instalação local          |
* Docker                    |  links para
* Máquinas virtuais         |  os guias
* Contêineres Linux         |

Implantação e escalonamento
---------------------------

Morbi sed scelerisque ligula. In dictum lacus quis felis
facilisisvulputate. Quisque lacinia condimentum ipsum
laoreet tempus.

* Implantar uma instância   |  links para
* Escalar sua aplicação     |  os guias

Problemas bidimensionais

Um mais difícil problema é quando a estrutura delineada pelo Diátaxis encontra outra estrutura - frequentemente, uma estrutura de áreas temáticas dentro da documentação, ou quando a documentação encontra tipos de usuários muito diferentes.

Por exemplo, podemos ter um produto que é usado na terra, no mar e no ar e, embora seja o mesmo produto, é usado de forma bastante diferente em cada caso. E pode ser que um usuário que o utilize na terra tenha pouca probabilidade de usá-lo no mar.

Ou a documentação do produto atende às necessidades de:

• usuários

• desenvolvedores que criam outros produtos ao redor dele

• os contribuidores que ajudam a mantê-lo.

O mesmo produto, mas preocupações muito diferentes.

Um exemplo final: um produto que pode ser implantado em diferentes nuvens públicas, com cada nuvem pública apresentando fluxos de trabalho, comandos, APIs, interfaces gráficas (GUIs), restrições e assim por diante bastante diferentes. Embora seja o mesmo produto, no que diz respeito aos usuários em cada caso, o que eles precisam saber e fazer é muito diferente - o que eles precisam é de documentação não para o produto, mas para

• produto-na-nuvem-pública-um

• produto-na-nuvem-pública-dois

• e assim por diante…

Então, poderíamos decidir por uma estrutura geral que faça isso:

tutorial
    para usuários na terra
        [...]
    para usuários no mar
        [...]
    para usuários no ar
        [...]
[e assim por diante para guias de como fazer, referência e explicação]

ou talvez, em vez disso, isto:

para usuários na terra
    tutorial
        [...]
    guias de como fazer
        [...]
    referência
        [...]
    explicação
        [...]
para usuários no mar
    [seções de tutorial, como fazer, referência e explicação]
para usuários no ar
    [seções de tutorial, como fazer, referência e explicação]

Qual é o melhor? Parece haver muita repetição em ambos os casos. E quanto ao material que pode ser compartilhado entre terra, mar e ar?

Qual é o problema?

Primeiramente, o problema não está de forma alguma limitado ao Diátaxis - haveria a dificuldade de gerenciar a documentação de qualquer maneira. No entanto, o Diátaxis certamente ajuda a revelar o problema, como faz em muitos casos. Ele o traz para o foco e exige que seja abordado.

Em segundo lugar, a questão destaca um mal-entendido comum. O Diátaxis não é um esquema no qual a documentação deva ser inserida - quatro caixas. Ele propõe quatro tipos diferentes de documentação, em torno dos quais a documentação deve ser estruturada, mas isso não significa que deva haver simplesmente quatro divisões de documentação na hierarquia, uma para cada uma dessas categorias.

Diátaxis como uma abordagem

O Diátaxis pode ser representado de forma limpa em um diagrama - mas ele não é o mesmo que esse diagrama.

Ele deve ser entendido como uma abordagem, uma forma de trabalhar com documentação, que identifica quatro necessidades diferentes e as utiliza para redigir e estruturar a documentação de forma eficaz.

Isso tenderá a uma divisão estrutural clara e explícita nas quatro categorias - mas esse é um resultado típico de uma boa prática, não o seu fim.

Pensamento voltado ao usuário

O Diátaxis é fundamentado na atenção às necessidades do usuário, e mais uma vez é essa preocupação que deve nos direcionar.

O que devemos documentar é o produto como ele é para o usuário, o produto como ele está em suas mãos e mentes. (Infelizmente para os criadores de produtos, como eles os concebem é muito menos relevante.)

O produto na terra, no mar e no ar são efetivamente três produtos diferentes, talvez para três usuários diferentes?

Nesse caso, que esse seja o ponto de partida para pensar sobre isso.

Se a documentação precisa atender às necessidades de usuários, desenvolvedores e contribuidores, como eles veem o produto? Devemos assumir que um desenvolvedor que o incorpora em outros produtos normalmente precisará de uma boa compreensão de como ele é usado, e que um contribuidor precisa saber o que um desenvolvedor sabe também?

Then, talvez faça sentido ser mais livre com a estrutura, em algumas partes (digamos, o tutorial) permitindo que o conteúdo voltado para o desenvolvedor siga o material voltado para o usuário, enquanto separa completamente os guias de como fazer dos contribuidores de ambos.

E assim por diante. Se a estrutura não for a estrutura simples e descomplicada com a qual começamos, isso não é um problema - contanto que haja um arranjo de acordo com os princípios do Diátaxis, de modo que a documentação não confunda suas diferentes formas e propósitos.

Deixe a documentação ser complexa se necessário

A documentação deve ser tão complexa quanto necessário. Ela às vezes terá estruturas complexas.

But, mesmo estruturas complexas podem se tornar fáceis de navegar, desde que sejam lógicas e incorporem padrões que se ajustem às necessidades dos usuários.