texto usado até agora na primeira seção de tutoriais TYPO3:
“este documento é um tutorial. Tutoriais são projetados para ser instruções passo a passoespecificamente criado para orientar um iniciante através de uma tarefa específica do início toend. Para facilitar a aprendizagem eficaz, os tutoriais fornecem exemplos para ilustrar os assuntos que cobrem. Além disso, os tutoriais fornecem orientação sobre como evitarcasas comuns e destacar conceitos-chave que devem ser lembrados para referência futura.”
De olhar para a literatura mencionada abaixo, devemos considerar os seguintes pontos-chave:
- um tutorial é uma lição, de aprendizado orientado, mostrando os passos para concluir algo, fazendo com que o leitor mais qualificada
- o leitor deve conseguir algo com significado e experiência de sucesso, achar que é factível e agradável, aumentar a competência, ganhar confiança, e quer fazê-lo novamente.
- concentre-se no conhecimento prático, não no conhecimento teórico. Aprenda um novo ofício ou habilidade, concentre-se em aprender fazendo
Diretrizes:
- permita que o usuário aprenda fazendo,
- vá do simples ao complexo
- comece o usuário
- não há problema em mostrar as etapas que o iniciante entende melhor. “melhores práticas” podem ser algo diferente. Como um usuário experiente faria isso pode ser algo diferente.
- o objetivo é iniciar o leitor, não levá-lo a um destino final.
- certifique-se de que seu tutorial funciona!
- inspire a confiança do iniciante: no software, no tutorial, no tutor e, claro, em sua própria capacidade de alcançar o que está sendo solicitado a eles.
- garantir que o usuário veja os resultados imediatamente
- a conclusão de cada seção de um tutorial, ou o tutorial como um todo, deve ser uma realização significativa.
- seu tutorial deve ser repetível de forma confiável.
- concentre-se em etapas concretas, não em conceitos abstratos. A tentação de introduzir abstração é enorme: resista!
- Fornecer o mínimo necessário explicação
- Foco apenas sobre os passos que o usuário precisa ter
Literatura¶
- Ubuntu: Como escrever um tutorial
- Daniele Procida: “o Que ninguém fala sobre documentação(19 de Maio de 2017) – muito boa A postagem no blog sobre diferentes tipos de manuais.