Skip to main content

Guias práticos

Guias práticos são direções que conduzem o leitor através de um problema ou em direção a um resultado. Guias práticos são orientados a objetivos.

Um guia prático ajuda o usuário a realizar algo de forma correta e segura; ele orienta a ação do usuário.

Ele lida com o trabalho - navegar de um lado ao outro de um campo de problemas do mundo real.

Exemplos podem ser: como calibrar a matriz de radar; como usar fixtures no pytest; como configurar políticas de reconexão com back-off. Por outro lado, como construir uma aplicação web não é - isso não aborda um objetivo ou problema específico, é uma esfera de habilidade vastamente ampla.

Guias práticos importam não apenas porque os usuários precisam ser capazes de realizar coisas: a lista de guias práticos em sua documentação ajuda a delinear o quadro do que seu produto realmente pode fazer. Uma lista rica de guias práticos é uma sugestão encorajadora das capacidades de um produto.

Guias práticos bem escritos que abordam as perguntas certas provavelmente serão as seções mais lidas da sua documentação.

Guias práticos direcionados a problemas​

Guias práticos devem ser escritos a partir da perspectiva do usuário, não da maquinaria. Um guia prático representa algo que alguém precisa realizar. Em outras palavras, ele é definido pelas necessidades de um usuário. Em outras palavras, todo guia prático deve responder a um projeto humano. Ele deve mostrar o que o ser humano precisa fazer, com as ferramentas disponíveis, para obter o resultado de que precisa.

Isso contrasta fortemente com o padrão comum para guias práticos que frequentemente prevalece, no qual os guias práticos são definidos por operações que podem ser executadas com uma ferramenta ou sistema. O problema com este último padrão é que ele oferece pouco valor ao usuário; ele não é direcionado a nenhuma necessidade que o usuário tenha. Em vez disso, ele é focado na ferramenta, em fazer a maquinaria passar por seus movimentos.

Esta é fundamentalmente uma distinção de significado. O significado é dado pelo propósito e pela necessidade. Não há propósito ou necessidade na funcionalidade de uma máquina. Trata-se meramente de uma série de causas e efeitos, entradas e saídas.

Considere:

  • “Para fechar o fluxo de água, gire a torneira no sentido horário.”

  • “Para fazer o deploy da configuração de banco de dados desejada, selecione as opções apropriadas e pressione Deploy.”

Os exemplos acima parecem exemplos de orientação, mas não são.

Eles representam informações majoritariamente inúteis que qualquer pessoa com competência básica - qualquer pessoa que trabalhe neste domínio - deve saber. Entre eles, interfaces padronizadas e conhecimento geralmente esperado devem deixar bem claro qual efeito a maioria das ações terá.

Em segundo lugar, eles estão desconectados do propósito. O que o usuário precisa saber pode ser coisas como:

  • quanta água executar e com que vigor executá-la para um determinado propósito

  • quais opções de configuração de banco de dados se alinham a necessidades particulares do mundo real

As ferramentas aparecem em guias práticos como coadjuvantes incidentais, o meio para o fim do usuário. Às vezes, é claro, um determinado fim está intimamente alinhado com uma ferramenta ou parte específica do sistema, e então você descobrirá que um guia prático de fato se concentra nisso. Com igual frequência, um guia prático abrangerá diferentes ferramentas ou partes de um sistema, unindo-as em uma série de atividades definidas por algo que um ser humano precisa realizar. Em qualquer dos casos, é esse projeto que define o que um guia prático deve cobrir.

O que os guias práticos não são​

Guias práticos são totalmente distintos de tutoriais. Eles são frequentemente confundidos, mas as necessidades dos usuários que eles atendem são bastante diferentes. Confundi-los está na raiz de muitas dificuldades que afetam a documentação. Consulte A diferença entre um tutorial e um guia prático para uma discussão sobre esta distinção.

Em outra confusão, guias práticos são frequentemente interpretados apenas como guias procedimentais. Mas resolver um problema ou realizar uma tarefa nem sempre pode ser reduzido a um procedimento. Problemas do mundo real nem sempre se prestam a soluções lineares. As sequências de ação em um guia prático às vezes precisam se ramificar e se sobrepor, e possuem múltiplos pontos de entrada e saída. Frequentemente, um guia prático exigirá que o usuário confie em seu julgamento ao aplicar a orientação que ele pode fornecer.

Princípios-chave​

Um guia prático lida com o trabalho - uma tarefa ou problema, com um objetivo prático. Mantenha o foco nesse objetivo.

Qualquer outra coisa adicionada distrai tanto você quanto o usuário e dilui o poder útil do guia. Normalmente, as tentações são explicar ou fornecer referência para fins de completude. Nenhuma dessas opções faz parte de guiar o usuário em seu trabalho. Elas atrapalham a ação; se forem importantes, faça um link para elas.

Um guia prático serve ao trabalho do usuário já competente, de quem você pode presumir que sabe o que quer fazer e que é capaz de seguir suas instruções corretamente.

Aborde a complexidade do mundo real​

Um guia prático precisa ser adaptável a casos de uso do mundo real. Um guia que seja inútil para qualquer propósito exceto exatamente o escopo restrito que você abordou raramente é valioso. Você não pode abordar todos os casos possíveis, portanto, deve encontrar maneiras de permanecer aberto à gama de possibilidades, de modo que o usuário possa adaptar sua orientação às necessidades dele.

Omitir o desnecessário​

Em guias práticos, a usabilidade prática é mais útil do que a completude. Enquanto um tutorial precisa ser um guia completo de ponta a ponta, um guia prático não precisa ser. Ele deve começar e terminar em algum lugar razoável e significativo, e exigir que o leitor o conecte ao seu próprio trabalho.

Forneça um conjunto de instruções​

Um guia prático descreve uma solução executável para um problema ou tarefa do mundo real. Ele está na forma de um contrato: se você estiver enfrentando esta situação, poderá superá-la seguindo as etapas delineadas nesta abordagem. As etapas estão na forma de ações.

“Ações” neste contexto inclui atos físicos, mas também pensamento e julgamento - resolver um problema envolve pensar sobre ele. Um guia prático deve abordar tanto a forma como o usuário pensa quanto o que o usuário faz.

Descreva uma sequência lógica​

A estrutura fundamental de um guia prático é uma sequência. Isso implica ordenação lógica no tempo, que há sentido e significado nessa ordem específica.

Em muitos casos, a ordenação é simplesmente imposta pela maneira como as coisas devem ser (a etapa dois exige a conclusão da etapa um, por exemplo). Nesse caso, é óbvio qual ordem suas direções devem tomar.

Às vezes, a necessidade é mais sutil - pode ser possível executar duas operações em qualquer ordem, mas se, por exemplo, uma operação ajudar a configurar o ambiente de trabalho do usuário ou até mesmo o seu raciocínio de uma forma que beneficie a outra, essa é uma boa razão para colocá-la primeiro.

Busque fluidez​

A todo momento, tente fundamentar suas sequências nos padrões das atividades e do pensamento do usuário, de modo que o guia adquira fluidez: progresso suave.

Alcançar fluidez significa compreender com sucesso o usuário. Prestar atenção ao sentido e ao significado na ordenação exige prestar atenção à maneira como os seres humanos pensam e agem, e às necessidades de alguém que segue instruções.

Novamente, isso pode ser um tanto óbvio: um workflow que faz o usuário alternar repetidamente entre contextos e ferramentas é claramente desajeitado e ineficiente. Mas você deve olhar mais profundamente do que isso. Sobre o que você está pedindo para o usuário pensar, e como o pensamento dele fluirá de assunto para assunto durante o trabalho? Por quanto tempo você exige que o usuário retenha pensamentos antes que eles possam ser resolvidos em ação? Se você exige que o usuário retorne a preocupações anteriores, isso é necessário ou evitável?

Um guia prático está preocupado não apenas com a ordenação lógica no tempo, mas com a ação ocorrendo no tempo. A ação, e um guia para ela, tem ritmo e cadência. Um ritmo mal julgado ou uma cadência interrompida são prejudiciais à fluidez.

Em seu melhor estado, a documentação prática proporciona fluidez ao usuário. Há uma experiência distinta de encontrar um guia que parece antecipar o usuário - o equivalente na documentação de um ajudante que tem a ferramenta que você estava prestes a pegar, pronta para colocá-la em sua mão.

Preste atenção à nomeação​

Escolha títulos que digam exatamente o que um guia prático mostra.

  • bom: How to integrate application performance monitoring

  • ruim: Integrating application performance monitoring (talvez o documento seja sobre como decidir se você deve, não sobre como fazê-lo)

  • muito ruim: Application performance monitoring (talvez seja sobre como - mas talvez seja sobre se, ou mesmo apenas uma explicação de o que é)

Observe que os mecanismos de busca apreciam bons títulos tanto quanto os humanos.

A linguagem dos guias práticos​

Este guia mostra como…

Descreva claramente o problema ou a tarefa que o guia mostra ao usuário como resolver.

Se você quer x, faça y. Para alcançar w, faça z.

Use imperativos condicionais.

Consulte o guia de referência x para obter uma lista completa de opções.

Não polua seu guia prático com todas as coisas possíveis que o usuário possa fazer relacionadas a x.

Aplicado a alimentos e culinária​

Considere uma receita, um modelo excelente para um guia prático. Uma receita define claramente o que será alcançado ao segui-la e aborda uma pergunta específica ( Como faço para…? ou O que posso fazer com…?).

Não é responsabilidade de uma receita ensinar você a fazer algo. Um chef profissional que fez exatamente a mesma coisa várias vezes antes ainda pode seguir uma receita - mesmo que tenha criado a receita ele mesmo - para garantir que faça da maneira correta.

Mesmo seguir uma receita exige pelo menos competência básica. Não se deve esperar que alguém que nunca cozinhou antes siga uma receita com sucesso, portanto, uma receita não substitui uma aula de culinária.

Alguém que esperava receber uma receita e recebe em troca uma aula de culinária ficará desapontado e aborrecido. Da mesma forma, embora seja interessante ler sobre o contexto ou a história de um prato específico, a única hora em que você não quer se deparar com isso é enquanto está no meio da tentativa de prepará-lo. Uma boa receita segue um formato bem estabelecido, que exclui tanto o ensino quanto a discussão, e foca apenas em como preparar o prato em questão.