Skip to main content

Tutoriais

Um tutorial é uma experiência que ocorre sob a orientação de um tutor. Um tutorial é sempre orientado ao aprendizado.

Um tutorial é uma atividade prática, na qual o aluno aprende fazendo algo significativo em direção a um objetivo alcançável.

Um tutorial serve para a aquisição de habilidades e conhecimentos pelo usuário — o seu estudo. O objetivo não é ajudar o usuário a concluir uma tarefa, mas sim ajudá-lo a aprender.

Em outras palavras, um tutorial é uma lição.

É importante compreender que, embora o aluno aprenda fazendo, o que o aluno faz não é necessariamente o que ele aprende. Ao fazer, ele adquirirá conhecimento teórico (ou seja, fatos), compreensão e familiaridade. Ele aprenderá como as coisas se relacionam e interagem entre si, e como interagir com elas. Ele aprenderá os nomes das coisas, o uso de ferramentas, workflows, conceitos e comandos. E assim por diante.

O tutorial como uma lição​

Uma lição envolve uma relação entre um professor e um aluno. Em todo aprendizado desse tipo, o aprendizado ocorre à medida que o aluno se dedica a 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 do professor são muito menos importantes.

Uma boa lição dá confiança ao aluno, mostrando-lhe que ele pode ser bem-sucedido em uma determinada habilidade ou com um determinado produto.

Obrigações do professor​

Uma lição é uma espécie de contrato entre professor e aluno, no qual quase toda a responsabilidade recai sobre o professor. O professor tem a responsabilidade 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 neste contrato é estar atento e seguir as instruções do professor o mais closely possível. Não há responsabilidade por parte do aluno de aprender, compreender ou lembrar.

Ao mesmo tempo, o exercício a que você submete seus alunos deve ser:

  • significativo - o aluno precisa ter uma sensação de realização

  • bem-sucedido - o aluno precisa ser capaz de concluí-lo

  • lógico - o caminho que o aluno percorre através dele precisa fazer sentido

  • completamente útil - 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 executados, 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 não têm tutoriais totalmente; os tutoriais são frequentemente confundidos com guias de como fazer (how-to guides).

Em uma lição ideal, o professor está presente, interage e responde ao aluno, corrigindo seus erros e verificando seu aprendizado. Na documentação, nada disso é possível.

Já é difícil montar uma experiência de aprendizado que atenda a todos os padrões descritos acima; em muitos contextos, o produto em si evolui rapidamente, o que significa que todo esse trabalho precisa ser refeito para garantir que o tutorial ainda desempenhe suas funções necessárias.

Você também descobrirá frequentemente que nenhuma outra parte da sua documentação está sujeita a revisões da mesma forma que seus tutoriais. Em outras partes da documentação, alterações e melhorias geralmente podem ser feitas de forma discreta; nos tutoriais, onde a jornada de aprendizado de ponta a ponta deve fazer sentido, elas frequentemente se propagam por toda a narrativa.

Finalmente, 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 apenas deve 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 entregue tudo isso de alguma forma.

Princípios-chave​

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 precoces e frequentes, concretude e assim por diante — não são segredos, mas nem sempre são bem compreendidos.

Ainda assim, existem maneiras diretas e eficazes de abordar os problemas da 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 espécie de ansiedade para transmitir conhecimento e compreensão, mas se você ceder a isso e tentar ensinar contando e explicando, você jeopardizará a experiência de aprendizado.

Em vez disso, permita que o aprendizado ocorra e confie que ele acontecerá. Dê ao seu aluno coisas para fazer, através das quais ele possa aprender. Apenas o seu aluno pode aprender. Infelizmente, por mais que você deseje, você não poderá aprender pelo seu aluno. Você não pode fazê-lo aprender. Tudo o que você pode fazer é viabilizar para que ele possa aprender.

Mostre ao aluno para onde ele irá​

É importante permitir que o aluno forme uma ideia do que ele alcançará desde o início. Além de ajudar a definir expectativas, isso permite que ele se veja construindo em direção à meta concluída 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 faremos o deploy de uma aplicação web escalável. Ao longo do caminho, encontraremos ferramentas e serviços de conteinerizaçã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 cedo e frequentemente​

Seu aluno provavelmente está fazendo coisas novas e estranhas que ele não compreende totalmente. A compreensão vem da capacidade de fazer conexões entre causas e efeitos, portanto, deixe-os ver os resultados e fazer 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 etapa que o aluno segue deve produzir um resultado compreensível, por menor que seja.

Mantenha uma narrativa do que é esperado​

Em cada etapa de um tutorial, o usuário experimenta um momento de ansiedade: esta ação produzirá o resultado correto? Parte do trabalho de um tutorial bem-sucedido é continuar fornecendo feedback ao aluno de que ele está de fato no caminho certo.

Mantenha uma narrativa de expectativas: “Você notarão que…”; “Após alguns momentos, o servidor responde com…”. (Nota: ajuste o tom formal para o imperativo/impessoal ou segunda pessoa conforme o contexto, mantendo o padrão de tradução profissional). Mostre ao usuário exemplos reais de saída ou até mesmo a saída exata esperada.

Se você souber com antecedência quais são os sinais prováveis de erro, considere sinalizá-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 requer 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, um aluno geralmente está focado demais no que está fazendo para notar esses sinais, a menos que seja instigado pelo professor.

Seu trabalho como professor é fechar os ciclos de aprendizado apontando 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 meramente passiva. Significa prestar atenção ao ambiente, uma habilidade em si. Isso é frequentemente negligenciado.

Aponte para a sensação de fazer​

Em toda habilidade ou ofício, o praticante experiente experimenta uma sensação de fazer, um propósito unificado, ação, pensamento e resultado.

À medida que a habilidade se desenvolve, ela flui em um ritmo confiante e se torna uma espécie de prazer. É o prazer de caminhar, por exemplo.

A habilidade do seu aluno depende de ele descobrir essa sensação e de ela se tornar um prazer.

Seu desafio como criador de um tutorial é garantir que suas tarefas unam propósito e ação para que se tornem um berço para essa sensação.

Encoraje e permita a repetição​

Os alunos retornarão e repetirão um exercício que lhes dê sucesso, pelo prazer que encontram em obter o resultado esperado. Fazer isso reafirma para eles que eles conseguem fazer e que funciona.

A repetição é a chave para estabelecer a sensação de fazer; estar familiarizado com essa sensação é uma camada fundamental do aprendizado.

No seu tutorial, tente tornar possível que uma etapa e um resultado específicos sejam repetidos. Isso pode ser difícil, por exemplo, em operações que não são reversíveis (tornando difícil voltar a uma etapa anterior) — mas busque isso sempre que puder. Ao observar um usuário seguindo um tutorial, você muitas vezes se surpreenderá ao ver com que frequência ele escolhe repetir uma etapa. Eles estão fazendo isso apenas para ver que a mesma coisa realmente acontece de novo.

Minimize implacavelmente a explicação​

Um tutorial não é o lugar para explicações. Em um tutorial, o usuário está focado em seguir suas instruções corretamente e obter os resultados esperados. Mais tarde, quando estiverem prontos, eles buscarão explicações, mas agora eles estão preocupados em fazer. A explicação distrai a atenção deles disso e bloqueia o aprendizado.

Por exemplo, é perfeitamente suficiente dizer algo como: Estamos usando HTTPS porque é mais seguro. Há um momento para discussão aprofundada e explicação do 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 resistir para um professor; até 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, confiamos no poder da abstração para estruturá-lo para nós mesmos — e é assim que queremos estruturá-lo para os outros. Compreender significa apreender ideias gerais, e a abstração é a forma lógica da compreensão — mas não é disso que precisamos em um tutorial, e não é assim que o aprendizado ou o ensino bem-sucedido funcionam.

É preciso ver por si mesmo para ver a atenção focada de um estudante se dissolver no ar, quando a explicação bem-intencionada de um professor quebra o feitiço mágico do aprendizado.

… e foque no concreto​

Em uma situação de aprendizado, seu aluno está no momento, um momento composto de coisas concretas. Você é responsável por configurar e manter o fluxo do aluno, de uma ação concreta e resultado para outro.

Foque em este problema, esta ação, este resultado, de forma a conduzir o aluno de passo a passo concreto.

Pode parecer que, ao manter o foco no concreto e particular, você nega ao aluno a oportunidade de ver ou compreender os padrões gerais mais amplos, mas o oposto é verdadeiro. A única coisa que nossas mentes fazem espetacularmente bem é perceber padrões gerais a partir de exemplos concretos. Todo aprendizado move-se em uma direção: do concreto e particular para o geral e abstrato. Este último surgirá a partir do primeiro.

Ignore opções e alternativas​

Seu trabalho é guiar o aluno a uma conclusão bem-sucedida. Pode haver muitas digressões interessantes ao longo do caminho (diferentes opções para o comando que você está usando, diferentes maneiras de usar a API, diferentes abordagens para a tarefa que você está descrevendo) — ignore-as. Sua orientação precisa permanecer focada no que é necessário para alcançar a conclusão, e todo o resto pode ser deixado para outra ocasião.

Fazer isso ajuda a manter seu tutorial mais curto e direto, poupando tanto você quanto o leitor de ter que realizar trabalho cognitivo extra.

Aspire à confiabilidade perfeita​

Todos os itens acima são princípios gerais da pedagogia, mas há um peso 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 estágio, 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 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, de forma que seu tutorial funcione para todos os usuários, todas as vezes.

É um trabalho árduo 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 as descobrirá sozinho; terá que contar com os usuários para descobri-las para você. A única maneira de aprender quais são é descobrindo o que realmente acontece quando os usuários realizam o tutorial, através de testes extensivos e observação.

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 nessa.

Neste tutorial, nós vamos…

Descreva o que o aluno realizará.

Primeiro, faça x. Agora, faça y. Agora que você fez y, faça z.

Nenhum espaço para ambiguidade ou dúvida.

Devemos sempre fazer x antes de fazermos y porque… (consulte Explicação para mais detalhes).

Forneça explicação mínima das ações na linguagem mais básica possível. Link para explicações mais detalhadas.

A saída deve se parecer com algo como…

Dê expectativas claras ao seu aluno.

Note que… Lembre-se de que… Vamos verificar…

Dê muitas pistas ao seu aluno para ajudar a confirmar que ele está no caminho certo e a se orientar.

Você construiu um motor de estase hilomórfica de três camadas e seguro…

Descreva (e admire, de forma branda) o que seu aluno realizou.

Aplicado à comida e à culinária​

Alguém que já teve a experiência de ensinar uma criança a cozinhar entenderá o que importa em um tutorial e, com igual importância, as coisas que não importam em absoluto.

Realmente não importa o que a criança faz, ou quão corretamente ela o faz. O valor de uma lição reside no que a criança ganha, e não no que ela produz.

O sucesso em uma aula de culinária com uma criança não é o resultado culinário ou se a criança consegue agora repetir os processos sozinha. O sucesso ocorre 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 prazer na experiência de estar na cozinha com você e queira retornar a ela. A aprendizagem de uma habilidade nunca é uma questão definitiva e única. 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 tempo dela, no ritmo dela, através das atividades que vocês fazem juntos, e não a partir das coisas que você diz ou mostra.

Com uma criança pequena, você frequentemente descobrirá que a lição precisa terminar de repente antes que você tenha concluído o que pretendia fazer. Isso é normal e esperado; as crianças têm curto período de atenção. Mas, desde que a criança tenha conseguido alcançar algo — por menor que seja — e tenha gostado de fazer, ela terá lançado bases na construção de sua expertise técnica, às quais poderá retornar e sobre as quais poderá construir na próxima vez.