Tutoriais
Um tutorial é uma experiência que ocorre sob a orientação de um tutor. Um tutorial é sempre voltado para o aprendizado.
Um tutorial é uma atividade prática, na qual o estudante aprende fazendo algo significativo, em direção a algum objetivo alcançável.
Um tutorial serve à aquisição de habilidades e conhecimentos pelo usuário — o seu estudo. Seu propósito não é ajudar o usuário a realizar alguma tarefa específica, mas sim ajudá-lo a aprender.
Um tutorial, em outras palavras, é uma lição.
É importante entender que, embora o estudante aprenda fazendo, o que o estudante faz não é necessariamente o que ele aprende. Ao fazer, ele adquirirá conhecimento teórico (ou seja, fatos), entendimento, familiaridade. Ele aprenderá como as coisas se relacionam e interagem entre si, e como interagir com elas. Ele aprenderá o nome das coisas, o uso de ferramentas, fluxos de trabalho, conceitos, comandos, e assim por diante.
O tutorial como uma lição
Uma lição implica uma relação entre um professor e um aluno. Em todo aprendizado desse tipo, o aprendizado ocorre à medida que o aluno se aplica às tarefas sob a orientação do instrutor.
Uma lição é uma experiência de aprendizado. Em uma experiência de aprendizado, o que importa é o que o aluno faz e o que acontece. Em contrapartida, as explicações e recitações de fatos pelo professor são muito menos importantes.
Uma boa lição dá confiança ao aluno, mostrando-lhe que ele pode ter sucesso em uma determinada habilidade ou com um determinado produto.
Obrigações do professor
Uma lição é um tipo de contrato entre professor e aluno, no qual quase toda a responsabilidade recai sobre o professor. O professor é responsável pelo que o aluno deve aprender, pelo que o aluno fará para aprender e pelo sucesso do aluno. Enquanto isso, a única responsabilidade do aluno nesse contrato é estar atento e seguir as instruções do professor da forma mais precisa possível. Não há responsabilidade do aluno em aprender, compreender ou lembrar.
Ao mesmo tempo, o exercício pelo qual você conduz seus alunos deve ser:
-
significativo — o aluno precisa ter uma sensação de conquista
-
bem-sucedido — o aluno precisa ser capaz de completá-lo
-
lógico — o caminho que o aluno percorre precisa fazer sentido
-
utilmente completo — o aluno deve ter contato com todas as ações, conceitos e ferramentas com os quais precisa se familiarizar
O problema dos tutoriais
Em geral, os tutoriais raramente são bem feitos, em parte porque são genuinamente difíceis de fazer bem e em parte porque não são bem compreendidos. No software, muitos produtos carecem de bons tutoriais, ou carecem totalmente de tutoriais; os tutoriais são frequentemente confundidos com guias de como fazer.
Em uma lição ideal, o professor está presente, interage com o aluno e responde a ele, corrigindo seus erros e verificando seu aprendizado. Na documentação, nada disso é possível.
Já é bastante difícil estruturar uma experiência de aprendizado que atenda a todos os padrões descritos acima; em muitos contextos, o próprio produto evolui rapidamente, o que significa que todo esse trabalho precisa ser feito novamente para garantir que o tutorial ainda desempenhe as funções exigidas.
Você também notará frequentemente que nenhuma outra parte de sua documentação está sujeita a revisões da forma como seus tutoriais estão. Em outras partes da documentação, alterações e melhorias geralmente podem ser feitas de forma isolada; nos tutoriais, onde a jornada de aprendizado de ponta a ponta deve fazer sentido, as mudanças frequentemente se propagam por toda a história.
Por fim, os tutoriais contêm a complicação adicional da distinção entre o que deve ser aprendido e o que deve ser feito. O criador de um tutorial não deve apenas ter uma boa noção do que o usuário deve aprender e quando, mas também deve conceber uma jornada de aprendizado significativa que, de alguma forma, entregue tudo isso.
Princípios fundamentais
Um tutorial é um problema pedagógico.
Não é um problema fácil, mas também não é um mistério. Os princípios descritos abaixo — repetição, ação, pequenos passos, resultados rápidos e frequentes, concretude e assim por diante — não são segredos, mas nem sempre são bem compreendidos.
Mesmo assim, existem maneiras simples e eficazes de abordar os problemas de pedagogia na prática.
A primeira regra do ensino é simplesmente: não tente ensinar. Seu trabalho, como professor, é fornecer ao aluno uma experiência que lhe permita aprender. Um professor inevitavelmente sente uma ansiedade em transmitir conhecimento e entendimento, mas se você ceder a isso e tentar ensinar dizendo e explicando, colocará em risco a experiência de aprendizado.
Em vez disso, permita que o aprendizado ocorra e confie que ocorrerá. Dê ao seu aluno coisas para fazer, através das quais ele possa aprender. Apenas o seu aluno pode aprender. Infelizmente, por mais que deseje, você não será capaz de aprender pelo seu aluno. Você não pode fazê-lo aprender. Tudo o que você pode fazer é tornar possível que ele aprenda.
Mostre ao aluno para onde ele está indo
É importante permitir que o aluno forme uma ideia do que alcançará desde o início. Além de ajudar a definir expectativas, permite que ele se veja progredindo em direção ao objetivo final enquanto trabalha.
Fornecer a imagem de que o aluno precisa em um tutorial pode ser tão simples quanto informá-lo no início: Neste tutorial, criaremos e implantaremos uma aplicação web escalável. Ao longo do caminho, encontraremos ferramentas e serviços de containerização.
Isso não é o mesmo que dizer: Neste tutorial você aprenderá… — o que é presunçoso e um padrão muito ruim.
Entregue resultados visíveis rápidos e frequentes
Seu aluno provavelmente está fazendo coisas novas e estranhas que não entende completamente. O entendimento vem de ser capaz de fazer conexões entre causas e efeitos, então permita que ele veja os resultados e faça as conexões de forma rápida e repetida. Cada um desses resultados deve ser algo que o usuário possa ver como significativo.
Cada passo que o aluno segue deve produzir um resultado compreensível, por menor que seja.
Mantenha uma narrativa sobre o esperado
A cada passo de um tutorial, o usuário experimenta um momento de ansiedade: esta ação produzirá o resultado correto? Parte do trabalho de um tutorial de sucesso é continuar fornecendo feedback ao aluno de que ele está de fato no caminho certo.
Mantenha uma narrativa de expectativas: "Você notará que …"; "Após alguns instantes, o servidor responde com …". Mostre ao usuário a saída real de exemplo, ou até mesmo a saída exata esperada.
Se você souber com antecedência quais são os sinais prováveis de erro, considere apontá-los: "Se a saída não mostrar …, você provavelmente esqueceu de …".
É útil preparar o usuário para ações possivelmente surpreendentes: "O comando provavelmente retornará várias centenas de linhas de logs no seu terminal."
Aponte o que o aluno deve notar
O aprendizado exige reflexão. Isso acontece em múltiplos níveis e profundidades, mas um dos primeiros é quando o aluno observa os sinais em seu ambiente. Em uma lição, o aluno geralmente está focado demais no que está fazendo para notá-los, a menos que seja alertado pelo professor.
Seu trabalho como professor é fechar os ciclos de aprendizado apontando as coisas, de passagem, à medida que a lição avança. Isso pode ser tão simples quanto apontar como um prompt de linha de comando muda, por exemplo.
Observar é uma parte ativa de um ofício, não apenas passiva. Significa prestar atenção ao ambiente, uma habilidade em si. Muitas vezes é negligenciada.
Foque no sentimento de fazer
Em qualquer habilidade ou ofício, o profissional realizado experimenta um sentimento de fazer, um propósito unificado de ação, pensamento e resultado.
À medida que a habilidade se desenvolve, ela flui em um ritmo confiante e se torna um tipo de prazer. É o prazer de caminhar, por exemplo.
A habilidade do seu aluno depende de ele descobrir esse sentimento e de que isso se torne um prazer.
Seu desafio como criador de um tutorial é garantir que suas tarefas unam propósito e ação para que se tornem a base para esse sentimento.
Incentive e permita a repetição
Os alunos retornarão e repetirão um exercício que lhes proporcione sucesso, pelo prazer de obter o resultado esperado. Fazer isso reafirma que eles conseguem fazer e que funciona.
A repetição é fundamental para estabelecer o sentimento de fazer; estar familiarizado com esse sentimento é uma camada fundamental do aprendizado.
Em seu tutorial, tente tornar possível a repetição de um determinado passo e resultado. Isso pode ser difícil, por exemplo, em operações que não são reversíveis (tornando difícil voltar a um passo anterior) — mas busque isso onde puder. Assistindo a um usuário seguir um tutorial, você muitas vezes se surpreenderá ao ver quantas vezes ele escolhe repetir um passo. Ele faz isso apenas para ver se a mesma coisa realmente acontece novamente.
Minimize a explicação de forma implacável
Um tutorial não é o lugar para explicações. Em um tutorial, o usuário está focado em seguir corretamente suas instruções e obter os resultados esperados. Mais tarde, quando estiver pronto, ele buscará explicações, mas agora ele está preocupado em fazer. A explicação distrai sua atenção disso e bloqueia seu aprendizado.
Por exemplo, é perfeitamente suficiente dizer algo como: Estamos usando HTTPS porque é mais seguro. Há um lugar para discussões e explicações detalhadas sobre o HTTPS, mas não agora. Em vez disso, forneça um link ou referência para essa explicação, para que ela esteja disponível, mas não atrapalhe.
A explicação é uma das tentações mais difíceis de um professor resistir; mesmo professores experientes acham difícil aceitar que o aprendizado de seus alunos não depende de explicações. Isso é perfeitamente natural. Uma vez que compreendemos algo, contamos com o poder da abstração para enquadrá-lo para nós mesmos — e é assim que queremos enquadrá-lo para os outros. Entender significa captar ideias gerais, e a abstração é a forma lógica do entendimento — mas isso não é o que precisamos em um tutorial, e não é assim que o aprendizado ou o ensino de sucesso funcionam.
É preciso ver por si mesmo para notar a atenção concentrada de um aluno se dissolver no ar quando a explicação bem-intencionada de um professor quebra o encanto do aprendizado.
… e foque no concreto
Em uma situação de aprendizado, seu aluno está no momento presente, um momento composto por coisas concretas. Você é responsável por estabelecer e manter o fluxo do aluno, de uma ação e resultado concretos para outro.
Foque deste problema, desta ação, deste resultado, de forma a guiar o aluno de passo em passo concreto.
Pode parecer que, ao manter o foco no concreto e no particular, você nega ao aluno a oportunidade de ver ou compreender os padrões gerais mais amplos, mas o contrário é verdadeiro. A única coisa que nossas mentes fazem espetacularmente bem é perceber padrões gerais a partir de exemplos concretos. Todo aprendizado se move em uma direção: do concreto e particular para o geral e abstrato. Este último emergirá do primeiro.
Ignore opções e alternativas
Seu trabalho é guiar o aluno a uma conclusão bem-sucedida. Pode haver muitos desvios interessantes ao longo do caminho (opções diferentes para o comando que você está usando, maneiras diferentes de usar a API, abordagens diferentes para a tarefa que você está descrevendo) — ignore-os. Sua orientação precisa permanecer focada no que é necessário para chegar à conclusão, e todo o resto pode ser deixado para outra ocasião.
Fazer isso ajuda a manter seu tutorial mais curto e objetivo, e poupa tanto você quanto o leitor de ter que fazer trabalho cognitivo extra.
Aspire à confiabilidade perfeita
Tudo o que foi dito acima são princípios gerais de pedagogia, mas há um fardo especial sobre o criador de um tutorial.
Um tutorial deve inspirar confiança. A confiança só pode ser construída camada por camada e é facilmente abalada. Em cada etapa, quando você pede ao seu aluno para fazer algo, ele deve ver o resultado que você promete. Um aluno que segue suas instruções e não obtém os resultados esperados perderá rapidamente a confiança no tutorial, no tutor e em si mesmo.
Um professor que está presente com o aluno pode resgatá-lo quando as coisas dão errado. Em um tutorial, você não pode fazer isso. Seu tutorial deve ser tão bem construído que as coisas não possam dar errado, que seu tutorial funcione para todo usuário, todas as vezes.
Dá trabalho criar uma experiência confiável, mas é a isso que você deve aspirar ao criar um tutorial.
Seu tutorial terá falhas e lacunas, por mais cuidadosamente que seja escrito. Você não descobrirá todas sozinho, terá que contar com os usuários para descobri-las por você. A única maneira de saber quais são é descobrindo o que realmente acontece quando os usuários fazem o tutorial, por meio de testes e observações extensivas.
A linguagem dos tutoriais
Nós …
A primeira pessoa do plural afirma a relação entre tutor e aluno: você não está sozinho; estamos juntos nisso.
Neste tutorial, nós iremos …
Descreva o que o aluno irá realizar.
Primeiro, faça x. Agora, faça y. Agora que você fez y, faça z.
Sem espaço para ambiguidade ou dúvida.
Devemos sempre fazer x antes de fazermos y porque… (consulte Explicação para mais detalhes).
Forneça uma explicação mínima das ações na linguagem mais básica possível. Faça um link para uma explicação mais detalhada.
A saída deve se parecer com …
Dê ao seu aluno expectativas claras.
Note que … Lembre-se de que … Vamos verificar …
Dê ao seu aluno pistas abundantes para ajudar a confirmar que ele está no caminho certo e a se orientar.
Você construiu um motor de estase hilomórfico de três camadas seguro…
Descreva (e admire, de forma moderada) o que seu aluno realizou.
Aplicado a comida e culinária
Quem já teve a experiência de ensinar uma criança a cozinhar entenderá o que importa em um tutorial e, de forma igual, as coisas que não importam nem um pouco.
Realmente não importa o que a criança faz, ou o quão corretamente ela faz. O valor de uma lição está no que a criança ganha, não no que ela produz.
O sucesso de uma aula de culinária com uma criança não é o resultado culinário, ou se a criança pode agora repetir os processos sozinha. O sucesso é quando a criança adquire o conhecimento e as habilidades que você esperava transmitir.
Uma condição crucial para isso é que a criança descubra o prazer na experiência de estar na cozinha com você e queira voltar. Aprender uma habilidade nunca é uma questão definitiva. A repetição é sempre necessária.
Enquanto isso, a aula de culinária pode ser estruturada em torno da ideia de aprender a preparar um prato específico, mas o que realmente precisamos que a criança aprenda podem ser coisas como: que lavamos as mãos antes de manusear alimentos; como segurar uma faca; por que o óleo deve estar quente; como se chama este utensílio, como cronometrar e medir as coisas.
A criança aprende tudo isso trabalhando ao seu lado na cozinha; no seu próprio tempo, no seu próprio ritmo, através das atividades que fazem juntos, e não pelas coisas que você diz ou mostra.
Com uma criança pequena, muitas vezes você notará que a aula de repente precisa terminar antes de você ter completado o que se propôs a fazer. Isso é normal e esperado; as crianças têm tempos de atenção curtos. Mas, desde que a criança tenha conseguido realizar algo — por menor que seja — e tenha gostado de fazer, isso terá lançado uma base na construção de sua especialidade técnica, sobre a qual ela poderá retornar e construir da próxima vez.