Compreender Aprender
Compreender as abstrações e os modelos mentais em que o produto se baseia.
Os produtos de software geralmente são construídos em torno de abstrações difíceis de compreender, mas fundamentais para o uso correto de uma aplicação ou serviço. Embora a documentação conceitual nem sempre seja consultada primeiro, é frequentemente usada em conjunto com a documentação de exploração e prática para consolidar o aprendizado.
Exemplos de documentação que ajuda a compreender são Concepts do Kubernetes, Thinking in React e What is OLAP?. Todos oferecem explicações conceituais sobre ideias que implementam ou introduzem. Ao fazer isso, ultrapassam as fronteiras dos próprios produtos e se tornam materiais de aprendizado universais.
Embora seja difícil de produzir e fácil de subestimar, a documentação que promove a compreensão também serve a iniciativas educacionais, como academias de produto ou salas de aula. É valiosa porque está no centro dos Circles of Product Truth. Todo conjunto de documentação deve atender a essa necessidade.
O que o usuário quer fazer
Os produtos de software se baseiam em abstrações difíceis de compreender, mas fundamentais para o uso correto. A documentação conceitual consolida o aprendizado ao lado da exploração e da prática.
Sinais de que a documentação não atende a essa necessidade
- Os usuários conseguem operar o produto, mas não explicar por que ele funciona daquele jeito.
- Os conceitos só são explicados em comentários no código ou em wikis internos.
- Não existe um glossário ou guia conceitual para as abstrações fundamentais do produto.
Dois exemplos reais
Tipos de conteúdo comuns
| DITA | Diátaxis | Good Docs Project |
|---|---|---|
| <concept>, <glossentry>, <section> | Explicação | Guia conceitual, Glossário |
Uma métrica
cobertura de conceitos · Proporção das abstrações fundamentais com uma página conceitual dedicada.