{"actions":[{"alt":"Discernir","definition":"Discernir as principais qualidades do produto e, se for o caso, compará-lo com outros.","description":"Os usuários da documentação são também potenciais clientes ou adotantes. Quem lê deve conseguir discernir as principais qualidades do produto e compará-lo com outros. Trata-se de um processo de descoberta.","examples":[{"title":"What is Databricks?","url":"https://docs.databricks.com/en/introduction/index.html"},{"title":"Splunk Observability Cloud Service Description","url":"https://docs.splunk.com/observability/en/get-started/service-description.html"}],"frameworks":{"diataxis":["Sem equivalente direto (o mais próximo é Explicação)"],"dita":["\u003ctopic\u003e","\u003cconcept\u003e"],"good_docs":["Visão geral","Página de destino"]},"id":"appraise","metric":{"description":"Taxa de conversão da documentação para a adoção do produto.","name":"conversão"},"signals":["As equipes de suporte e vendas respondem repetidamente às mesmas perguntas: “O que é isso?”","Os potenciais clientes descobrem o que o produto faz no material de marketing, não na documentação.","Não existe uma página que apresente o posicionamento ou os principais pontos fortes do produto."],"verb":"Avaliar"},{"alt":"Descobrir","definition":"Experimentar o produto e descobrir o que ele faz, com uma barreira de entrada baixa.","description":"Os grandes produtos convidam os usuários a interagir e a experimentar coisas novas. A documentação deve oferecer pistas, instruções e possibilidades de ação que facilitem a exploração como uma das primeiras atividades.","examples":[{"title":"React Quick Start","url":"https://react.dev/learn"},{"title":"Tour of Go","url":"https://go.dev/tour/welcome/1"}],"frameworks":{"diataxis":["Tutorial"],"dita":["\u003ctask\u003e","\u003cstep\u003e","\u003csubstep\u003e"],"good_docs":["Tutorial"]},"id":"explore","metric":{"description":"Tempo entre a primeira visita e a primeira interação bem-sucedida.","name":"tempo até o primeiro valor"},"signals":["Os novos usuários não encontram um guia de início rápido nem um ambiente de testes para experimentar o produto.","A primeira experiência é uma parede de material de referência, não uma visita guiada.","Os usuários precisam ler um manual inteiro antes de poder usar o produto."],"verb":"Explorar"},{"alt":"Relembrar","definition":"Relembrar informações que não foi possível memorizar, de parâmetros a códigos de erro.","description":"O material de referência mantém a documentação viva depois de anos de uso. Os usuários consultam manuais para recordar, relembrar, recuperar ou procurar informações que não conseguiram memorizar.","examples":[{"title":"Dockerfile reference","url":"https://docs.docker.com/reference/dockerfile/"},{"title":"GitLab CI/CD YAML syntax reference","url":"https://docs.gitlab.com/ee/ci/yaml/"}],"frameworks":{"diataxis":["Referência"],"dita":["\u003creference\u003e","\u003crefsyn\u003e","\u003cproperties\u003e"],"good_docs":["Referência","Glossário"]},"id":"remember","metric":{"description":"Proporção das consultas ao material de referência que retornam a página certa.","name":"taxa de acerto das consultas"},"signals":["Os usuários procuram um parâmetro ou código de erro e não encontram nada.","O material de referência está espalhado por posts de blog e históricos de conversas.","Não existe uma referência estruturada e pesquisável para a sintaxe ou as configurações do produto."],"verb":"Recordar"},{"alt":"Solucionar","definition":"Diagnosticar e resolver problemas de forma eficiente, muitas vezes sob pressão.","description":"Esbarrar em problemas — configurações incorretas, casos extremos ou erros reais — é comum. A resolução de problemas representa a necessidade de diagnosticá-los e resolvê-los de forma eficiente, muitas vezes sob pressão, quando os sistemas falham ou os prazos se aproximam.","examples":[{"title":"Kubernetes Debug Pods","url":"https://kubernetes.io/docs/tasks/debug/debug-application/debug-pods/"},{"title":"Elasticsearch Troubleshooting","url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/fix-common-cluster-issues.html"}],"frameworks":{"diataxis":["Guia prático (orientado ao problema)"],"dita":["\u003ctroubleshooting\u003e","\u003ctrouble\u003e","\u003ccause\u003e","\u003cremedy\u003e"],"good_docs":["Guia de resolução de problemas"]},"id":"troubleshoot","metric":{"description":"Tempo mediano entre o sintoma e a volta a um estado funcional.","name":"tempo de resolução"},"signals":["Os chamados de suporte repetem a mesma pergunta e a resposta está no histórico de uma conversa, não na documentação.","As mensagens de erro aparecem no código, mas nunca na documentação.","Os usuários procuram uma mensagem de erro e chegam a uma página que não a menciona."],"verb":"Resolver"},{"alt":"Integrar","definition":"Construir sobre o produto, ampliá-lo ou integrá-lo para criar valor adicional.","description":"Os usuários precisam com frequência construir sobre produtos existentes, ampliá-los ou integrá-los, por meio de integrações, extensões, plugins ou aplicações totalmente novas. O objetivo é quase sempre pragmático.","examples":[{"title":"Vercel Approval Checklist","url":"https://vercel.com/docs/integrations/create-integration/approval-checklist"},{"title":"Chrome Debug extensions","url":"https://developer.chrome.com/docs/extensions/get-started/tutorial/debug"}],"frameworks":{"diataxis":["Guia prático"],"dita":["\u003ctask\u003e","\u003ccodeblock\u003e","\u003ccoderef\u003e"],"good_docs":["Guia prático","Referência de API"]},"id":"develop","metric":{"description":"Número de integrações ou extensões criadas pelos usuários.","name":"crescimento do ecossistema"},"signals":["As perguntas sobre integração e extensão ficam sem resposta ou são encaminhadas para um fórum.","Não existe um guia para construir sobre o produto.","Os pontos de extensão do produto não estão documentados."],"verb":"Desenvolver"},{"alt":"Treinar","definition":"Aprender a usar o produto nas operações cotidianas e habituais.","description":"Os usuários precisam aprender a usar a maior parte das áreas de um produto. Praticar descreve a necessidade de adquirir conhecimento procedimental: como usar o produto nas operações cotidianas e habituais.","examples":[{"title":"Generating a new SSH key (GitHub)","url":"https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent"},{"title":"Import contacts to MailChimp","url":"https://mailchimp.com/help/import-contacts-mailchimp/"}],"frameworks":{"diataxis":["Guia prático"],"dita":["\u003ctask\u003e","\u003cstep\u003e","\u003cchoicetable\u003e"],"good_docs":["Guia prático"]},"id":"practice","metric":{"description":"Proporção de usuários que concluem um procedimento padrão sem suporte.","name":"sucesso da tarefa"},"signals":["As mesmas perguntas sobre como fazer algo se repetem nos canais de suporte e da comunidade.","Os procedimentos existem apenas como conhecimento informal ou na cabeça de alguém.","Não existe um guia passo a passo para tarefas administrativas comuns."],"verb":"Praticar"},{"alt":"Aprender","definition":"Compreender as abstrações e os modelos mentais em que o produto se baseia.","description":"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.","examples":[{"title":"Kubernetes Concepts","url":"https://kubernetes.io/docs/concepts/overview/components/"},{"title":"Thinking in React","url":"https://react.dev/learn/thinking-in-react"}],"frameworks":{"diataxis":["Explicação"],"dita":["\u003cconcept\u003e","\u003cglossentry\u003e","\u003csection\u003e"],"good_docs":["Guia conceitual","Glossário"]},"id":"understand","metric":{"description":"Proporção das abstrações fundamentais com uma página conceitual dedicada.","name":"cobertura de conceitos"},"signals":["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."],"verb":"Compreender"}],"model":{"canonical":"https://passo.uno/seven-action-model/","description":"Um modelo descritivo das necessidades dos usuários de documentação técnica. Sete ações abrangem os objetivos que quem consulta a documentação pode querer alcançar: Avaliar, Compreender, Explorar, Praticar, Recordar, Desenvolver e Resolver.","license":"CC BY 4.0","source":"https://passo.uno/seven-action-model/index.md","title":"Modelo de documentação de sete ações","version":"2025-01-09"}}