Por que a documentação de produtos tecnológicos é tão difícil de usar? (no ponto de vista do usuário)

Hoje em dia, nossa documentação de ferramentas de desenvolvedor é difícil de usar e tendemos a encontrar a solução em outras fontes, como Youtube, problemas do GitHub ou postagens de blog. Seu conteúdo pode facilmente ficar para trás ou o ponto-chave não foi mencionado. Considero esta questão um problema emergente que devemos alternar o mais rápido possível, e acho que dois grandes problemas precisavam ser resolvidos primeiro. (Na visão do usuário)

• A documentação é muito difícil de contribuir
  • A documentação torna-se facilmente desatualizada. As pessoas tendem a escrever um post de blog em vez de contribuir para um documento porque requer muito esforço extra sem os incentivos correspondentes.
• O contexto é agrupado

  • A documentação em si dificilmente se conecta a outros recursos. O contexto que faz uma boa documentação é agrupado.

    
    

Neste artigo, gostaria de apresentar dois conceitos sobre documentação que considero problemáticos e, em seguida, expandi-los para três pontos de pensamento para resolver esses dois problemas.

Em primeiro lugar, lembre-se de alguma documentação que você visitou recentemente e junte-se a mim com a explicação abaixo. Eu gostaria de usar o Next.js como exemplo, que atualmente é minha documentação mais visitada. Vamos começar com a página "Introdução".

https://nextjs.org/docs/getting-started

A documentação do Nextjs tem uma estrutura que é popular em vários produtos, deixe-me chamar essa estrutura de "Estrutura de listagem isolada". A razão pela qual os chamo de isolados é que eles são mantidos principalmente pelas pessoas por trás do Next.js (embora sejam de código aberto).

Além disso, gostaria de concluir a mentalidade por trás desta documentação como "ponto do proprietário".

Ponto do proprietário

A razão pela qual eu o chamo de "ponto do proprietário" é que o processo de geração de documentação geralmente é realizado pelo proprietário do produto. No início de um produto, ninguém tem um entendimento melhor do que o proprietário. Os proprietários são a melhor pessoa para manter a documentação adequada para seus consumidores e mantenedores.

Mas depois de um tempo, o produto recebe muito amor e começa a construir a comunidade. Torna-se cada vez mais difícil acompanhar casos de canto e bugs. Os proprietários precisam acompanhar novos commits e resolver problemas diariamente; por outro lado, eles precisam explicar novos designs, fazer advertências e fornecer informações para os novatos superarem esses problemas. O carregamento está aumentando drasticamente.

Nem todo produto consegue alcançá-lo, o conteúdo começa a ficar para trás e algumas soluções podem existir nas postagens do blog de outras pessoas, nas respostas do StackOverflow, nos problemas do GitHub ou nas discussões. Um usuário precisa conectar essas soluções com os mecanismos de pesquisa, às vezes a solução na documentação está errada.

Estrutura de listagem isolada

A estrutura de listagem isolada é muito comum, no comércio eletrônico, em sites de uso geral, no telefone e na documentação. Está em toda parte.

A estrutura é principalmente arbitrária e opinativa, proveniente da mentalidade do "ponto do proprietário", devido ao proprietário ter que primeiro criar a árvore da estrutura, na ordem que considera mais adequada para o cliente.

A estrutura de listagem isolada é uma faca de dois gumes: para ser claro, não sou totalmente contra essa estrutura, ela é realmente útil em um contexto geral. Por exemplo, é bom para a exploração inicial e, se você estiver familiarizado com o documento, será muito fácil encontrar as informações que deseja.

Mas por outro lado é uma estrutura fixa, é difícil a estrutura evoluir e toda vez que o mantenedor quer acrescentar algo a mais, é difícil achar um local adequado se o dono não pensou bem desde o início. Além disso, os usuários não têm outra escolha a não ser explorar sua documentação. Eles têm apenas uma rota e não é suficiente.

Imagine uma estrutura dinâmica, como um gráfico direcionado por força (algo como o Obsidian pode realizar ou um diagrama de árvore, você pode encontrar muitos exemplos diretamente na seção de publicação [^1]). Não estou dizendo que gráficos direcionados por força ou diagramas de árvore são melhores do que estruturas de listagem isoladas. O que eu quero é encorajar a todos a não pensar de uma forma "listada", mas de uma forma mais "dinâmica", para que as pessoas possam escolher o que melhor se adapta às suas necessidades. Eles podem usar diagramas de árvore para explorar a estrutura e usar o gráfico direcionado por força para reconhecer a conexão entre os tópicos. Ou podemos criar uma nova estrutura desde o início que pode resolver alguns desses problemas.

Combinadas, a mentalidade e a estrutura levam ao problema que considero problemático, listado abaixo.

A documentação é muito difícil de contribuir

Em combinação com a mentalidade arbitrária de "ponto do marcador do proprietário" e a "estrutura de listagem isolada", o que temos é que a documentação atual só pode ser mantida adequadamente pelo proprietário, não há outra maneira fácil de contribuir para a documentação. O problema é duplo.

Primeiro, com base na mentalidade do "ponto do marcador do proprietário", o autor não quer que uma pessoa inexperiente estrague sua documentação e é muito difícil combinar o tom da documentação se você não gastar muito tempo mantendo-se alinhado com seus mantenedores.

Em segundo lugar, seu usuário não tem nenhum incentivo para contribuir com a documentação, as pessoas adoram seu produto, mas se não obtiverem nenhum crédito na construção do documento ou alguma propriedade sobre alguma página da documentação, não há incentivo.

Você pode argumentar que eles podem postar um problema e explicar sua sugestão, mas o problema permanece. A sensação de contribuir é muito simultânea, é como a sensação de comprar alguma coisa. Imagine um mundo paralelo, aqui, se você quiser comprar algo, você precisa escrever 200 palavras para descrever por que você quer comprar essas coisas e qual é o benefício para a comunidade.

Não há necessidade de impedir que as pessoas contribuam com documentação com burocracia. Precisamos criar outra estrutura que possa permanecer a autoridade da documentação e beneficiar a contribuição simultânea ao mesmo tempo.

O contexto é agrupado

O material de uma boa documentação não é apenas a documentação em si, mas as discussões, questões, postagens de blog relacionadas e vídeos correspondentes. Chamarei esses materiais de "Contextos".

Até recentemente tendemos a armazenar esses contextos de forma distribuída. Um projeto regular de código aberto armazena sua discussão no GitHub ou em um fórum de discussão, seus casos de uso em sites de produtos, questões diretamente nos problemas do GitHub e um site de documentação auto-hospedado em outro lugar. Além disso, há muito conteúdo gerado pela comunidade no YouTube e postagens em blogs pessoais.

Na realidade, o contexto de um produto torna-se agrupado. Eles não terão interconexão entre si. Pode haver uma discussão sobre a solução para o bug específico, mas não há link reverso na seção de documentação que mencionou esta solução. Infelizmente, temos que lidar com a realidade de que o link bidirecional não é o que a internet atual é capaz.

O contexto agrupado é volátil

Imagine uma situação em que você abre a documentação do produto e rapidamente descobre que a documentação não fornece uma solução; mais tarde, no mesmo dia, você encontra uma solução viável na postagem do blog de outra pessoa.

Neste momento, com a documentação atual, não há outra maneira de lembrar a outros desenvolvedores que eles podem resolver o mesmo problema com este método descrito na postagem do blog, você não pode adicionar uma referência à documentação. O que você pode fazer é abrir um problema (se for de código aberto) ou abrir uma discussão em um fórum para lembrar as pessoas sobre esta solução que em breve será inundada por outro conteúdo.

Toda solução útil em qualquer contexto precisa ser resistente à enxurrada de informações que temos no momento. Eles têm que entrar neste campo de batalha sem nenhum ponto de ancoragem além dos mecanismos de busca.

A lista incrível [^2] é uma boa ideia, eles fornecem uma maneira de deixar bons conteúdos permanecerem, mas eles têm o mesmo problema com a mentalidade de "Estrutura de listagem isolada" e "ponto de bala do proprietário".

Se a situação continuar como está…

A consequência imediata dessas questões será a “Documentação” que se julgará decaída com o tempo. Você pode dar uma olhada na documentação de algum gigante da tecnologia, incluindo a documentação dos serviços da web da Amazon ou a documentação da nuvem do Google, todos eles são opressores e difíceis de ler.

A pior sensação é que você está preso em um problema específico que não consegue encontrar na documentação e em nenhum outro lugar. Estaremos enfrentando esses tipos de situações mais se a estrutura de nossa documentação não puder se alinhar com o escopo do produto que usamos.

Pode parecer difícil criar um novo tipo de estrutura para superar esses problemas em primeiro lugar. Mas olhe de perto, poderíamos separar os problemas gerais em 3 perguntas para nos fazermos.

• Como encorajar os usuários a contribuir com a documentação e não interferir no propósito geral do documento? Podemos ter uma experiência mais interativa para a documentação? Um usuário pode contribuir diretamente com a documentação sem sair da página?

• Como reunir o contexto para uma melhor experiência de pesquisa que não dependa de soluções de pesquisa externas e traga a interconectividade de todos os contextos ao longo do caminho?

• Como experimentar uma nova estrutura que possa beneficiar a experiência do usuário e iterá-la ao longo do tempo, ou mesmo permitir que os usuários a escolham livremente?

  
  

https://twitter.com/EiffelFly

[^1]: página de publicação da Obsidian [^2]: sindresorhus/awesome