{"actions":[{"alt":"Discernir","definition":"Discernir as principais qualidades do produto e, se for caso disso, compará-lo com outros.","description":"Os utilizadores da documentação são também potenciais clientes ou avaliadores. 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 equipas de apoio e vendas respondem repetidamente às mesmas perguntas: «O que é isto?»","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 é possível fazer com uma baixa barreira à entrada.","description":"Os grandes produtos convidam os utilizadores 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é ao primeiro valor"},"signals":["Os novos utilizadores não encontram um guia de início rápido ou um ambiente de testes onde possam experimentar o produto.","A primeira experiência é uma parede de material de referência, não uma visita guiada.","Os utilizadores têm de ler um manual inteiro antes de poderem utilizar o produto."],"verb":"Explorar"},{"alt":"Relembrar","definition":"Relembrar informações que não foi possível memorizar, desde parâmetros até códigos de erro.","description":"O material de referência mantém a documentação viva após anos de utilização. Os utilizadores consultam os 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":"Percentagem das consultas ao material de referência que devolvem a página certa.","name":"taxa de sucesso das consultas"},"signals":["Os utilizadores procuram um parâmetro ou código de erro e não encontram nada.","O material de referência está disperso por artigos de blogues e históricos de conversas.","Não existe uma referência estruturada e pesquisável para a sintaxe ou as definições do produto."],"verb":"Recordar"},{"alt":"Solucionar","definition":"Diagnosticar e resolver problemas de forma eficiente, muitas vezes sob pressão.","description":"Deparar-se com configurações incorretas, casos extremos ou erros reais é comum. A resolução de problemas representa a necessidade de os diagnosticar e resolver 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 para o 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 recuperação de um estado funcional.","name":"tempo de resolução"},"signals":["Os pedidos de apoio repetem a mesma pergunta, e a resposta encontra-se 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 utilizadores 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 utilizadores precisam frequentemente de construir sobre produtos existentes, ampliá-los ou integrá-los, através 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 utilizadores.","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 utilizar o produto nas operações quotidianas e habituais.","description":"Os utilizadores têm de aprender a utilizar a maior parte das áreas de um produto. Praticar descreve a necessidade de adquirir conhecimento processual: como usar o produto nas operações quotidianas 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":"Percentagem de utilizadores que concluem um procedimento padrão sem apoio.","name":"sucesso da tarefa"},"signals":["As mesmas perguntas sobre como fazer algo repetem-se nos canais de apoio 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 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.","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 conceptual","Glossário"]},"id":"understand","metric":{"description":"Percentagem das abstrações fundamentais com uma página conceptual dedicada.","name":"cobertura de conceitos"},"signals":["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."],"verb":"Compreender"}],"model":{"canonical":"https://passo.uno/seven-action-model/","description":"Um modelo descritivo das necessidades dos utilizadores 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 7-Ações","version":"2025-01-09"}}