Pular para o conteúdo principal

Guias de Como Fazer

Guias de como fazer são instruções que guiam o leitor através de um problema ou em direção a um resultado. Guias de como fazer são voltados para objetivos.

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

Ele está preocupado com o trabalho — navegar de um lado para o outro de um campo de problemas do mundo real.

Exemplos poderiam ser: como calibrar a matriz de radar; como usar fixtures no pytest; como configurar políticas de recuo para reconexão. Por outro lado, como construir uma aplicação web não é — isso não está abordando um objetivo ou problema específico, é uma esfera imensamente aberta de habilidades.

Os guias de como fazer são importantes não apenas porque os usuários precisam ser capazes de realizar coisas: a lista de guias de como fazer em sua documentação ajuda a estruturar a imagem do que seu produto realmente pode fazer. Uma lista rica de guias de como fazer é uma sugestão encorajadora dos recursos de um produto.

Guias de como fazer bem escritos que abordam as perguntas certas provavelmente serão as seções mais lidas de sua documentação.

Guias de como fazer direcionados a problemas​

Os guias de como fazer devem ser escritos sob a perspectiva do usuário, não do maquinário. Um guia de como fazer representa algo que alguém precisa realizar. Ele é definido, em outras palavras, pelas necessidades do usuário. Cada guia de como fazer deve responder a um projeto humano. Ele deve mostrar o que o ser humano precisa fazer, com as ferramentas à mão, para obter o resultado que precisa.

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

Trata-se fundamentalmente de 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. Ela é apenas 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 implantar a 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 em grande parte inúteis que se espera que qualquer pessoa com competência básica — qualquer pessoa que esteja trabalhando neste domínio — saiba. Juntos, interfaces padronizadas e o 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:

  • como fazer correr a água, e com que vigor fazê-la correr, para um determinado propósito

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

As ferramentas aparecem nos guias de como fazer como personagens secundários incidentais, o meio para o fim do usuário. Às vezes, é claro, um determinado fim está intimamente alinhado com uma ferramenta específica ou parte do sistema, e então você descobrirá que um guia de como fazer se concentra de fato nisso. Com a mesma frequência, um guia de como fazer cruzará 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 um dos casos, é esse projeto que define o que um guia de como fazer deve cobrir.

O que os guias de como fazer não são​

Os guias de como fazer são totalmente distintos dos 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 de como fazer para uma discussão sobre essa distinção.

Em outra confusão, os guias de como fazer são frequentemente interpretados apenas como guias de procedimentos. Mas resolver um problema ou realizar uma tarefa nem sempre pode ser reduzido a um procedimento. Os problemas do mundo real nem sempre se oferecem a soluções lineares. As sequências de ação em um guia de como fazer às vezes precisam se bifurcar e se sobrepor, e têm múltiplos pontos de entrada e saída. Frequentemente, um guia de como fazer precisará que o usuário confie em seu julgamento para aplicar a orientação que ele pode fornecer.

Princípios fundamentais​

Um guia de como fazer está preocupado com o trabalho — uma tarefa ou problema com um objetivo prático. Mantenha o foco nesse objetivo.

Qualquer outra coisa que seja adicionada distrai você e o usuário e dilui o poder útil do guia. Normalmente, as tentações são explicar ou fornecer referência para completude. Nenhuma dessas coisas 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 de como fazer atende ao trabalho do usuário que já é competente, do qual se supõe saber o que quer fazer e ser capaz de seguir suas instruções corretamente.

Aborde a complexidade do mundo real​

Um guia de como fazer precisa ser adaptável a casos de uso do mundo real. Aquele que é inútil para qualquer propósito, exceto exatamente o estreito que você abordou, raramente é valioso. Você não pode abordar todos os casos possíveis, por isso deve encontrar maneiras de permanecer aberto à gama de possibilidades, de forma que o usuário possa adaptar sua orientação às suas necessidades.

Ometa o desnecessário​

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

Forneça um conjunto de instruções​

Um guia de como fazer descreve uma solução executável para um problema ou tarefa do mundo real. É na forma de um contrato: se você está enfrentando esta situação, então pode trabalhar para resolvê-la seguindo os passos descritos nesta abordagem. Os passos estão na forma de ações.

"Ações" nesse contexto incluem atos físicos, mas também pensamento e julgamento — resolver um problema envolve pensar sobre ele. Um guia de como fazer deve abordar como o usuário pensa, bem como o que o usuário faz.

Descreva uma sequência lógica​

A estrutura fundamental de um guia de como fazer é uma sequência. Ela implica uma ordenação lógica no tempo, que existe um sentido e significado para esta ordem específica.

Em muitos casos, a ordenação é simplesmente imposta pela forma como as coisas devem ser (o passo dois requer a conclusão do passo um, por exemplo). Neste caso, é óbvio qual ordem suas instruções devem tomar.

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

Busque o fluxo​

A todo momento, tente basear suas sequências nos padrões das atividades e pensamentos do usuário, de forma que o guia adquira fluxo: progresso suave.

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

Novamente, isso pode ser um pouco óbvio: um fluxo de trabalho 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 seu trabalho? Por quanto tempo você exige que o usuário mantenha pensamentos abertos antes que possam ser resolvidos em ação? Se você exigir que o usuário retorne a preocupações anteriores, isso é necessário ou evitável?

Um guia de como fazer se preocupa 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 avaliado ou interrompido prejudica o fluxo.

Na melhor das hipóteses, a documentação de como fazer dá fluxo ao usuário. Há uma experiência distinta ao 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 colocar na sua mão.

Preste atenção aos nomes​

Escolha títulos que digam exatamente o que um guia de como fazer mostra.

  • bom: Como integrar o monitoramento de desempenho da aplicação

  • ruim: Integrando o monitoramento de desempenho da aplicação (talvez o documento seja sobre como decidir se você deve fazer isso, não sobre como fazê-lo)

  • muito ruim: Monitoramento de desempenho da aplicação (talvez seja sobre como — mas talvez seja sobre se, ou apenas uma explicação sobre o que é)

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

A linguagem dos guias de como fazer​

Este guia mostra como…

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

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

Use imperativos condicionais.

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

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

Aplicado a comida e culinária​

Considere uma receita, um excelente modelo para um guia de como fazer. Uma receita define claramente o que será alcançado ao segui-la e aborda uma questão específica ( Como faço para fazer…? 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 ele mesmo tenha criado a receita — para garantir que a execute corretamente.

Mesmo seguir uma receita requer 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 uma aula de culinária ficará desapontado e irritado. Da mesma forma, embora seja interessante ler sobre o contexto ou a história de um prato específico, o único momento em que você não quer ser confrontado com isso é quando 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 se concentra apenas em como preparar o prato em questão.