A diferença entre um tutorial e um guia prático (how-to guide)
No Diátaxis, tutoriais e guias práticos são fortemente distinguidos. É uma distinção que muitas vezes não é feita; de fato, a confusão mais comum feita na documentação de produtos de software é entre o tutorial e o guia prático.
Portanto: qual é a diferença entre tutoriais e guias práticos? Por que isso importa? E por que eles são confundidos?
Essas são ótimas perguntas. Vamos começar pela última. Se a distinção é realmente tão importante, por que não é mais óbvia?
O que eles têm em comum
Em aspectos importantes, tutoriais e guias práticos são realmente semelhantes. Ambos são guias práticos: contêm direções para o usuário seguir. Eles não estão lá para explicar ou transmitir informações. Eles existem para guiar o usuário sobre o que fazer, em vez do que há para saber ou entender.
Ambos estabelecem etapas para o leitor seguir, e ambos prometem que, se o leitor seguir essas etapas, ele chegará a uma conclusão bem-sucedida. Nenhum deles faz muito sentido, exceto para o usuário que está com as mãos na máquina, pronto para realizar ações. Ambos descrevem sequências ordenadas de ações. Não é possível esperar sucesso a menos que você execute as ações na ordem correta.
Eles estão estreitamente relacionados e, como muitas relações próximas, podem ser confundidos à primeira vista.
O que importa é o que o usuário precisa
O Diátaxis insiste que o que importa na documentação são as necessidades do usuário, e é prestando atenção a isso que podemos distinguir corretamente entre tutoriais e guias práticos.
Às vezes o usuário está estudando, e às vezes o usuário está trabalhando. A documentação precisa atender a ambas as necessidades.
Um tutorial atende às necessidades do usuário que está estudando. Sua obrigação é proporcionar uma experiência de aprendizado bem-sucedida. Um guia prático atende às necessidades do usuário que está trabalhando. Eles estão lá para guiá-lo com segurança em sua prática clínica para realizar uma tarefa específica — eles servem ao seu trabalho. Estas são necessidades e obrigações completamente diferentes, e é por isso que a distinção entre tutoriais e guias práticos é importante: os tutoriais são orientados ao aprendizado, e os guias práticos são orientados a tarefas.
Estudando e trabalhando
Podemos considerar isso a partir da perspectiva de um exemplo real. Digamos que você esteja na medicina: um médico, alguém que precisa adquirir e aplicar as habilidades práticas e clínicas de sua profissão.
Como médico, às vezes você estará em situações de trabalho, aplicando suas habilidades, e às vezes estará em situações de estudo, adquirindo habilidades (todos os bons médicos, mesmo aqueles com longas carreiras, continuam estudando para aperfeiçoar suas habilidades).
Estudando
No início do seu treinamento, você aprenderá a suturar uma ferida. Você começará no laboratório com seus colegas estudantes, em bancadas com pequenos pads de pele à sua frente (pads de pele são blocos de material sintético em várias camadas que representam a epiderme, a gordura e outros tecidos). Eles têm dureza e textura semelhantes à carne humana e se comportam de maneira um tanto semelhante quando são cortados e costurados. Será fornecido exatamente o que você precisa — luvas, bisturi, agulha, linha e assim por diante — e passo a passo será mostrado o que fazer e o que acontecerá quando você fizer.
E então é a sua vez. Você pegará o bisturi e o deslizará hesitantemente sobre o topo do pad, fazendo um incisão ineficaz na camada superior (talvez um assistente de ensino brinque com você, perguntando o que esse pobre pad fez para merecer um arranhão tão desagradável). Seu vizinho parecerá consternado com a própria tentativa, um corte irregular de profundidades totalmente desiguais que se parece com algo de uma briga de faca.
Após algumas tentativas, com feedback e correção do tutor, você terá feito um corte mais ou menos limpo que passa principalmente pela camada de gordura sem cortar o músculo abaixo. Triunfo!
Mas agora lhe pedem para fechá-lo novamente com costura! Você observará o tutor demonstrar com habilidade e precisão, fechando a ferida no pad com alguns pontos limpos e uniformes. Você, por outro lado, vai atrapalhar-se com a linha. Você segurará as coisas com a mão errada e do jeito errado, colocando-as nos lugares errados. Você deixará cair a agulha. A linha vai escapar. Você receberá uma bronca por não manter a esterilidade.
Eventualmente, você conseguirá de fato costurar a ferida. Você perfurará a pele nos lugares errados e rasgará as bordas do corte. Seu resultado final será uma cena feia de pele esticada e franzida, com pontos grosseiros e desalinhados. Os assistentes de ensino terão algumas críticas a fazer mesmo sobre partes que você achava que tinha acertado.
Mas, você terá costurado sua primeira ferida. E você voltará a esta lição repetidas vezes, e pouco a pouco seu jeito desajeitado se transformará em prática confiante. Você terá adquirido competência básica. Você terá aprendido fazendo.
Isto é um tutorial. É uma lição, mantida com segurança nas mãos de um instrutor, um professor que zela pelos interesses de um aluno.
Trabalhando
Agora, vamos pensar no médico no trabalho. Como médico no trabalho, você já é competente. Você aprendeu e aperfeiçoou habilidades clínicas como sutura, bem como muitas outras, e é capaz de reuni-las diariamente para aplicá-las a situações médicas no mundo real.
Considere uma apendicectomia padrão. Um manual clínico listará o equipamento e o pessoal necessários na sala de cirurgia. Ele mostrará como posicionar os membros da equipe e como dispor as ferramentas, suportes e monitores necessários. Ele prosseguirá passo a passo pelas ações que a equipe precisará seguir, terminando com a transferência formal para a equipe pós-operatória.
O manual mostrará quais incisões precisam ser feitas onde, mas elas dependerão de você estar realizando um procedimento aberto ou laparoscópico, de você ter imagens pré-operatórias para se basear ou não, e assim por diante. Ele incluirá etapas especiais ou verificações a serem feitas no caso de um paciente infantil ou juvenil, ou ao converter para uma apendicectomia aberta no meio do procedimento. Muitas das etapas serão da forma se isso, então aquilo.
Ter um manual ajuda a garantir que todas as etapas sejam feitas na ordem correta e nenhuma seja omitida. Como equipe, vocês revisarão os detalhes de um procedimento para relembrar as etapas principais; às vezes, vocês o consultarão durante o próprio procedimento.
Mesmo para cirurgias de rotina, os manuais clínicos contêm listas de etapas e verificações. Esses manuais são guias práticos. Eles não estão lá para ensiná-lo — você já tem suas habilidades. Você já conhece esses processos. Eles estão lá para orientá-lo com segurança em sua prática clínica para realizar uma tarefa específica - eles servem ao seu trabalho.
Compreendendo a distinção
A distinção entre uma aula na faculdade de medicina e um manual clínico é a distinção entre um tutorial e um guia prático.
O objetivo de um tutorial é ajudar o aluno a adquirir competência básica.
O objetivo de um guia prático é ajudar o usuário já competente a executar uma tarefa específica corretamente.
Um tutorial proporciona uma experiência de aprendizado. As pessoas aprendem habilidades por meio de experiência prática e direta. O que importa no tutorial é o que o aluno faz e o que ele vivencia ao fazer isso.
Um guia prático direciona o trabalho do usuário.
O tutorial segue um caminho cuidadosamente gerenciado, começando em um ponto determinado e caminhando até uma conclusão. Ao longo desse caminho, o aprendiz deve ter os encontros que a lição exige.
O guia prático visa a um resultado bem-sucedido e conduz o usuário pelo caminho mais seguro e certeiro até a meta, mas o caminho não pode ser gerenciado: é o mundo real, e qualquer coisa pode aparecer para atrapalhar a jornada.
Um tutorial familiariza o aprendiz com o trabalho: com as ferramentas, a linguagem, os processos e a forma como o que ele está utilizando se comporta e responde, e assim por diante. Seu trabalho é apresentá-los, fabricando um encontro estruturado e repetível com eles.
O guia prático pode e deve presumir familiaridade com todos eles.
O tutorial ocorre em um ambiente planejado, um ambiente de aprendizado onde o máximo possível é definido com antecedência para garantir uma experiência bem-sucedida.
Um guia prático aplica-se ao mundo real, onde você precisa lidar com o que quer que ele apresente.
O tutorial elimina o imprevisto.
O guia prático deve se preparar para o imprevisto, alertando o usuário sobre essa possibilidade e fornecendo orientações sobre como lidar com ele.
O caminho de um tutorial segue uma única linha. Ele não oferece escolhas ou alternativas.
Um guia prático normalmente se bifurcará e terá branches, descrevendo diferentes rotas para o mesmo destino: Se isso, então aquilo. No caso de …, uma abordagem alternativa é…
Um tutorial deve ser seguro. Nenhum dano deve ocorrer ao aprendiz; deve ser sempre possível voltar ao início e recomeçar.
Um guia prático não pode prometer segurança; frequentemente há apenas uma chance de acertar.
Em um tutorial, a responsabilidade é do professor. Se o aprendiz tiver problemas, esse é o problema do professor para resolver.
Em um guia prático, o usuário tem a responsabilidade de entrar e sair de problemas por conta própria.
O aprendiz pode nem ter competência suficiente para fazer as perguntas que um tutorial responde.
Um guia prático pode presumir que o usuário está fazendo as perguntas certas em primeiro lugar.
O tutorial é explícito sobre coisas básicas - onde fazer as coisas, onde colocá-las, como manipular objetos. Ele aborda a experiência prática — no nosso exemplo médico, com que força pressionar, como segurar um instrumento; em um tutorial de software, pode ser onde digitar um comando ou quanto tempo esperar por uma resposta.
Um guia prático baseia-se nisso como conhecimento implícito - até mesmo conhecimento corporal.
Um tutorial é concreto e particular em sua abordagem. Ele se refere às ferramentas, materiais, processos e condições específicos, conhecidos e definidos que preparamos cuidadosamente para o aprendiz.
O guia prático precisa adotar uma abordagem geral: muitas dessas coisas serão impossíveis de saber com antecedência ou serão diferentes em cada caso do mundo real.
O tutorial ensina habilidades e princípios gerais que posteriormente podem ser aplicados a uma multidão de casos.
O usuário que segue um guia prático o faz para concluir uma tarefa específica.
Nenhuma dessas distinções é arbitrária. Todas elas emergem da distinção entre estudo e trabalho, que entendemos como uma distinção fundamental para compreender o que o usuário da documentação precisa.
O básico e o avançado
Uma confusão comum, mas compreensível, é ver a diferença entre tutoriais e guias práticos como sendo a diferença entre o básico e o avançado.
Afinal, os tutoriais são para aprendizes, enquanto os guias práticos são para profissionais já qualificados. Os tutoriais devem cobrir o básico, enquanto os guias práticos precisam lidar com complexidades que os aprendizes não deveriam enfrentar.
No entanto, a história é mais complexa. Considere um manual de procedimentos clínicos: pode ser um manual para um procedimento de rotina básico, de altíssima simplicidade. Pode descrever etapas para assuntos mundanos, como o preenchimento correto de papelada oo descarte de materiais específicos. Guias práticos podem, fazem e frequentemente devem cobrir procedimentos básicos.
Ao mesmo tempo, mesmo como médico qualificado, você se encontrará novamente em situações de treinamento. Algumas delas podem ser muito avançadas e especializadas, exigindo um alto nível de habilidade e experiência prévias.
Digamos que você seja um anestesista com muitos anos de experiência que participa de um curso: “Intubações neonatais difíceis”. A parte prática do curso será uma experiência de aprendizado: uma lição, mantida com segurança nas mãos dos instrutores, que o fará realizar exercícios específicos para desenvolver suas habilidades — exatamente como anos antes, quando você estava aprendendo a suturar sua primeira ferida.
A complexidade é totalmente diferente, no entanto, e o mesmo ocorre com a base de habilidades necessárias até mesmo para participar da experiência de aprendizado. Mas ela tem a mesma forma e atende ao mesmo tipo de necessidade que aquela aula muito anterior.
É o mesmo na documentação de software: um tutorial pode apresentar algo complexo ou avançado. E um guia prático pode cobrir algo básico ou bem conhecido. A diferença entre os dois reside na necessidade que eles atendem: o estudo do usuário ou o seu trabalho.
Segurança e sucesso
Compreender essas distinções e a razão para mantê-las é crucial para criar documentação bem-sucedida. Um manual clínico que confundisse educação com prática, que tentasse ensinar e ao mesmo tempo fornecer um guia para um procedimento do mundo real, seria um documento literalmente mortal. Ele mataria pessoas.
Em disciplinas como a documentação de software, nós escapamos ilesos de muita coisa, porque nossas confusões e erros raramente matam alguém. No entanto, podemos causar uma grande quantidade de pequenos transtornos e insatisfações aos nossos usuários, e adicionamos mais a isso todas as vezes que publicamos um tutorial ou guia prático que não compreende se seu propósito é ajudar o usuário em seu estudo — a aquisição de habilidades — ou em seu trabalho — a aplicação de habilidades.
Além disso, nós também nos prejudicamos. Os usuários não são obrigados a usar nosso produto. Se nossa documentação não os conduzir ao sucesso — se não atender às necessidades que eles têm em um estágio específico de seu ciclo de interação com nosso produto — eles encontrarão outra coisa que o faça, caso possam.
A confusão entre tutoriais e guias práticos não é de forma alguma a única feita entre diferentes tipos de documentação, mas é uma das mais fáceis de cometer. É também particularmente prejudicial, pois corre o risco de atrapalhar aqueles recém-chegados que esperamos transformar em usuários engajados. Para o bem desses usuários e do nosso próprio produto, acertar a distinção é a chave para o sucesso.