Writing a tutorial

Text used so far in the first section of TYPO3 tutorials:

"This document is a tutorial. Tutorials are designed to be step-by-step instructions specifically created to walk a beginner through a particular task from beginning to end. To facilitate effective learning, tutorials provide examples to illustrate the subjects they cover. In addition, tutorials provide guidance on how to avoid common pitfalls and highlight key concepts that should be remembered for future reference."

From looking at the literature mentioned below we should consider the following key points:

  • a tutorial is a lesson, learning oriented, showing steps to complete something, making the reader more knowledgable
  • the reader should achieve something meaningful and experience success, find it doable and enjoyable, enhance competence, gain confidence, and wants to do it again.
  • concentrate on practical knowledge, not theoretical knowledge. Learn a new craft or skill, concentrate on learning by by doing

Guidelines:

  • allow the user to learn by doing,
  • go from simple to complex
  • Get the user started
  • it’s ok to show the steps the beginner understands best. “best practice” may be something different. How an experienced user would do it may be something different.
  • The goal is to get the reader started, not to get them to a final destination.
  • Make sure that your tutorial works!
  • inspire the beginner’s confidence: in the software, in the tutorial, in the tutor and, of course, in their own ability to achieve what’s being asked of them.
  • Ensure the user sees results immediately
  • The conclusion of each section of a tutorial, or the tutorial as a whole, must be a meaningful accomplishment.
  • Your tutorial must be reliably repeatable.
  • Focus on concrete steps, not abstract concepts. The temptation to introduce abstraction is huge: resist!
  • Provide the minimum necessary explanation
  • Focus only on the steps the user needs to take

Literature