Compreender Aprender
Compreender as abstrações e os modelos mentais em que o produto se baseia.
Os produtos de software são geralmente construídos em torno de abstrações difíceis de compreender, mas fundamentais para a utilização correta de uma aplicação ou serviço. Embora a documentação conceptual nem sempre seja consultada em primeiro lugar, é frequentemente utilizada em conjunto com a documentação de exploração e prática para consolidar a aprendizagem.
Exemplos de documentação que ajuda a compreender são Concepts do Kubernetes, Thinking in React e What is OLAP?. Todos os exemplos oferecem explicações conceptuais sobre as ideias que implementam ou introduzem. Ao fazê-lo, ultrapassam as fronteiras dos próprios produtos e tornam-se materiais de aprendizagem universais.
Embora seja difícil de produzir e fácil de subestimar, a documentação que promove a compreensão também serve iniciativas educativas, como academias de produto ou salas de aula. É valiosa porque se encontra no centro dos Circles of Product Truth. Todos os conjuntos de documentação devem responder a esta necessidade.
O que o utilizador quer fazer
Os produtos de software baseiam-se em abstrações difíceis de compreender, mas fundamentais para uma utilização correta. A documentação conceptual consolida a aprendizagem ao lado da exploração e da prática.
Sinais de que a documentação não responde a esta necessidade
- Os utilizadores conseguem operar o produto, mas não explicar por que razão funciona daquela forma.
- Os conceitos só são explicados em comentários no código ou em wikis internos.
- Não existe um glossário ou guia conceptual 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 conceptual, Glossário |
Uma métrica
cobertura de conceitos · Percentagem das abstrações fundamentais com uma página conceptual dedicada.