A diferença entre um tutorial e um guia de como fazer
No Diátaxis, tutoriais e guias de como fazer são fortemente distinguidos. É uma distinção que frequentemente não é feita; na verdade, a fusão mais comum cometida na documentação de produtos de software é aquela entre o tutorial e o guia de como fazer.
Então: qual é a diferença entre tutoriais e guias de como fazer? Por que isso importa? E por que eles são confundidos?
Estas são todas boas perguntas. Vamos começar com a última. Se a distinção é realmente tão importante, por que ela não é mais óbvia?
O que eles têm em comum
Em aspectos importantes, os tutoriais e os guias de como fazer são de fato semelhantes. Ambos são guias práticos: contêm instruções para o usuário seguir. Eles não estão lá para explicar ou transmitir informações. Existem para guiar o usuário no que fazer, em vez do que há para saber ou entender.
Ambos estabelecem passos para o leitor seguir e prometem que, se o leitor seguir esses passos, chegará a uma conclusão bem-sucedida. Nenhum deles faz muito sentido, exceto para o usuário que está com as mãos no maquinário, pronto para agir. Ambos descrevem sequências ordenadas de ações. Você não pode esperar sucesso a menos que execute as ações na ordem correta.
Eles são intimamente relacionados e, como muitos parentes próximos, podem ser confundidos um com o outro à 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 de como fazer.
Às vezes, o usuário está estudando, e 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 é fornecer uma experiência de aprendizado bem-sucedida. Um guia de como fazer atende às necessidades do usuário que está trabalhando. Sua obrigação é ajudar o usuário a realizar uma tarefa. Essas são necessidades e obrigações completamente diferentes, e é por isso que a distinção entre tutoriais e guias de como fazer é importante: os tutoriais são orientados ao aprendizado e os guias de como fazer são orientados a tarefas.
No estudo e no trabalho
Podemos considerar isso sob a perspectiva de um exemplo real. Digamos que você seja da área médica: um médico, alguém que precisa adquirir e aplicar as habilidades práticas e clínicas do seu ofício.
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 aprimorar suas habilidades).
No estudo
Logo no início de seu treinamento, você aprenderá a suturar uma ferida. Você começará no laboratório com seus colegas de classe, em bancadas com pequenas placas de pele sintética à sua frente (placas de pele são blocos de material sintético em várias camadas que representam a epiderme, a gordura e outros tecidos. Elas possuem dureza e textura semelhantes à carne humana, e se comportam de maneira parecida quando cortadas e costuradas). Você receberá exatamente o que precisa - luvas, bisturi, agulha, linha e assim por diante - e, passo a passo, verá o que fazer e o que acontecerá quando o fizer.
E então chega a sua vez. Você pegará o bisturi e, hesitantemente, o passará pelo topo da placa, fazendo uma incisão ineficaz na camada superior (talvez um assistente de ensino brinque com você, perguntando o que essa pobre placa fez para merecer um arranhão tão feio). Seu colega ao lado olhará desanimado para sua própria tentativa, um corte irregular de profundidades muito desiguais que parece resultado de uma briga de faca.
Após algumas tentativas, com comentários e correções do tutor, você terá feito um corte mais ou menos limpo, que passa principalmente pela camada de gordura sem cortar o músculo subjacente. Um triunfo!
Mas agora pedem para você costurar de volta! Você assistirá ao tutor demonstrar com destreza e precisão, fechando a ferida na placa com alguns pontos limpos e uniformes. Você, por outro lado, vai se atrapalhar com a linha. Vai segurar as coisas com a mão errada, ao contrário, e colocá-las nos lugares errados. Vai derrubar a agulha. A linha vai escapar. Vai levar bronca por não manter a esterilização.
Eventualmente, você finalmente conseguirá 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 enrugada e pontos grosseiros e desordenados. Os assistentes de ensino terão críticas a fazer até mesmo sobre partes que você achava que tinha acertado.
Mas, você terá suturado sua primeira ferida. E voltará a esta lição repetidamente e, pouco a pouco, sua hesitação se transformará em uma prática confiante. Você terá adquirido a competência básica. Terá aprendido fazendo.
Isso é um tutorial. É uma lição, com segurança nas mãos de um instrutor, um professor que cuida dos interesses do aluno.
No trabalho
Agora, pensemos no médico no trabalho. Como médico trabalhando, você já é competente. Você aprendeu e aprimorou habilidades clínicas como sutura, além de muitas outras, e é capaz de reuni-las diariamente para aplicá-las em situações médicas no mundo real.
Considere uma apendectomia padrão. Um manual clínico listará os equipamentos e a equipe necessária na sala de cirurgia. Ele mostrará como posicionar os membros da equipe e como dispor as ferramentas, suportes e monitores necessários. Ele avançará 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 estará sujeito a variações de acordo com a situação: mostrará quais incisões precisam ser feitas e onde, mas elas dependerão se você está realizando um procedimento aberto ou laparoscópico, se tem exames de imagem pré-operatórios para se basear ou não, e assim por diante. Ele incluirá etapas ou verificações especiais a serem feitas no caso de um paciente bebê ou jovem, ou ao converter para uma apendectomia 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 realizadas na ordem correta e nenhuma seja omitida. Como equipe, vocês revisarão os detalhes de um procedimento para se lembrarem das etapas principais; às vezes, vocês o consultarão durante o próprio procedimento.
Even para operações cirúrgicas de rotina, os manuais clínicos contêm listas de etapas e verificações. Esses manuais são guias de como fazer. Eles não estão lá para ensinar você - você já tem suas habilidades. Você já conhece esses processos. Eles estão lá para guiar você 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 lição na faculdade de medicina e um manual clínico é a distinção entre um tutorial e um guia de como fazer.
Um tutorial tem como propósito ajudar o aluno a adquirir competência básica.
Um guia de como fazer tem como propósito ajudar o usuário já competente a realizar uma tarefa específica corretamente.
Um tutorial fornece uma experiência de aprendizado. As pessoas aprendem habilidades por meio de experiência prática direta. O que importa em um tutorial é o que o aprendiz faz e o que ele experimenta enquanto faz.
Um guia de como fazer direciona o trabalho do usuário.
O tutorial segue um caminho cuidadosamente gerenciado, começando em um ponto determinado e progredindo até a conclusão. Ao longo desse caminho, o aprendiz deve ter os encontros que a lição exige.
O guia de como fazer visa a um resultado bem-sucedido e guia o usuário pelo caminho mais seguro e garantido até o objetivo, mas o caminho não pode ser gerenciado: é o mundo real, e qualquer coisa pode surgir para interromper a jornada.
Um tutorial familiariza o aprendiz com o trabalho: com as ferramentas, a linguagem, os processos e a maneira como aquilo com que estão trabalhando se comporta e responde, e assim por diante. Seu papel é apresentá-los, criando um encontro estruturado e repetível com eles.
O guia de como fazer pode e deve assumir familiaridade com tudo isso.
O tutorial ocorre em um ambiente controlado, um cenário de aprendizado onde o máximo possível é definido com antecedência para garantir uma experiência bem-sucedida.
Um guia de como fazer se aplica ao mundo real, onde você tem que lidar com o que vier pela frente.
O tutorial elimina o inesperado.
O guia de como fazer deve preparar para o inesperado, alertando o usuário sobre essa possibilidade e fornecendo orientações sobre como lidar com ela.
O caminho de um tutorial segue uma linha única. Ele não oferece escolhas ou alternativas.
Um guia de como fazer normalmente se dividirá em ramificações, 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.
O guia de como fazer não pode prometer segurança; frequentemente, há apenas uma chance de acertar.
Em um tutorial, a responsabilidade cabe ao professor. Se o aprendiz tiver problemas, a correção é problema do professor.
Em um guia de como fazer, o usuário tem a responsabilidade de se meter e se livrar de problemas.
O aprendiz pode nem mesmo ter competência suficiente para fazer as perguntas que um tutorial responde.
Um guia de como fazer pode assumir 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 corporal - em 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 de como fazer confia nisso como conhecimento implícito - até mesmo conhecimento corporal.
O tutorial é concreto e particular em sua abordagem. Ele se refere a ferramentas, materiais, processos e condições específicos, conhecidos e definidos que colocamos cuidadosamente diante do aprendiz.
O guia de como fazer deve adotar uma abordagem geral: muitas dessas coisas serão desconhecidas com antecedência, ou diferentes em cada caso do mundo real.
O tutorial ensina habilidades e princípios gerais que, mais tarde, poderão ser aplicados a uma infinidade de casos.
O usuário que segue um guia de como fazer o faz para concluir uma tarefa específica.
Nenhuma dessas distinções é arbitrária. Todas elas surgem da distinção entre estudo e trabalho, que entendemos como uma distinção fundamental para dar sentido ao que o usuário da documentação precisa.
O básico e o avançado
Uma fusão comum, mas compreensível, é ver a diferença entre tutoriais e guias de como fazer como sendo a diferença entre o básico e o avançado.
Afinal, os tutoriais são para aprendizes, enquanto os guias de como fazer são para profissionais já qualificados. Os tutoriais devem cobrir o básico, enquanto os guias de como fazer precisam lidar com complexidades que os aprendizes não deveriam enfrentar.
No entanto, há mais nessa história. Considere um manual de procedimento clínico: ele pode ser um manual para um procedimento básico de rotina, de complexidade muito baixa. Ele pode descrever etapas para assuntos cotidianos, como o preenchimento correto de papelada ou o descarte de materiais específicos. Guias de como fazer podem, de fato e frequentemente devem, cobrir procedimentos básicos.
Ao mesmo tempo, mesmo como um médico qualificado, você se verá de volta a 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, sob a segurança dos instrutores, que fará você realizar exercícios específicos para desenvolver suas habilidades - exatamente como foi quando, anos antes, você estava aprendendo a suturar sua primeira ferida.
A complexidade é totalmente diferente, no entanto, e o mesmo vale para a base de habilidades exigida apenas para participar da experiência de aprendizado. Mas é da mesma forma e atende ao mesmo tipo de necessidade que aquela lição muito anterior.
O mesmo vale para a documentação de software: um tutorial pode apresentar algo complexo ou avançado. E um guia de como fazer pode cobrir algo básico ou bem conhecido. A diferença entre os dois está na necessidade que 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 uma documentação bem-sucedida. Um manual clínico que fundisse 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 documentação de software, nós nos safamos de muita coisa, porque nossas confusões e erros raramente matam alguém. No entanto, podemos causar muitos inconvenientes e insatisfações menores aos nossos usuários, e aumentamos isso toda vez que publicamos um tutorial ou guia de como fazer sem compreender se o 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 levar 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, se puderem.
A fusão de tutoriais e guias de como fazer não é de forma alguma a única cometida entre diferentes tipos de documentação, mas é uma das mais fáceis de cometer. É também uma fusão particularmente prejudicial, porque corre o risco de atrapalhar os recém-chegados que esperamos transformar em usuários engajados. Pelo bem desses usuários e de nosso próprio produto, acertar nessa distinção é a chave para o sucesso.