docs/tutorials/example_tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0f9cd670",
   "metadata": {},
   "source": [
    "# Quantum Prototype Tutorial\n",
    "\n",
    "In the software tutorial, the user needs to *do* things. The idea is to teach the user a wide range of tools and operations, building up from the simplest ones at the start to more complex ones."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aa14a920",
   "metadata": {},
   "source": [
    "## How to write a good tutorial\n",
    "(Adapted from <https://diataxis.fr/tutorials/#writing-a-good-tutorial>.  License: CC-BY-SA 4.0)\n",
    "\n",
    "### Don't try to teach\n",
    "\n",
    "Allow the user to learn. **In the beginning, we only learn anything by\n",
    "doing** - it's how we learn to talk, or walk.\n",
    "\n",
    "Give your learner things to do, through which they can learn. Only your\n",
    "pupil can learn. Sadly, however much you desire it, you will not be able\n",
    "to learn for your pupil. You cannot make them learn. All you can do is\n",
    "make it so *they* can learn.\n",
    "\n",
    "As you lead the pupil through the steps you have devised, have them use\n",
    "the tools and perform the operations they'll need to become familiar\n",
    "with, building up from the simplest ones at the start to more complex\n",
    "ones.\n",
    "\n",
    "### Get the user started\n",
    "\n",
    "Your job is to **get the learner started**, not to turn them into an\n",
    "expert. Don't ever be embarrassed to start right at the beginning: a\n",
    "user can skim rapidly over what's unnecessary, but if they need\n",
    "something and it's not there, you risk losing them altogether. It's also\n",
    "perfectly acceptable if what you get the beginner to do is not the way\n",
    "an experienced person would, or even if it's not the 'correct' way - a\n",
    "tutorial for beginners is not the same thing as a manual for best\n",
    "practice.\n",
    "\n",
    "The point of a tutorial is to help your learner set out safely on their\n",
    "journey, not to get them to a final destination.\n",
    "\n",
    "The only reason not to lower the threshold is because you decide that\n",
    "you don't want the responsibility of teaching beginners at below a\n",
    "certain level, or you judge that a certain level of skill is a\n",
    "reasonable prerequisite for using the product at all.\n",
    "\n",
    "### Provide a complete picture before they start\n",
    "\n",
    "It's important to **allow the learner to form an idea of what they will\n",
    "achieve right from the start**. As well as helping to set expectations,\n",
    "it allows them to see themselves building towards the completed goal as\n",
    "they work. Surprising them with the result at the end will diminish, not\n",
    "augment, the value of what they achieve. It's very enjoyable to reveal\n",
    "impressive conclusions with a flourish, but you should save that for\n",
    "your magic tricks and novels.\n",
    "\n",
    "Providing the picture the learner needs in a tutorial can be as simple\n",
    "as informing them at the outset: *In this tutorial you will build a\n",
    "simple website using Django and deploy it using Docker. Along the way\n",
    "you will use a cloud storage service for handling media files, and will\n",
    "configure your application to use it.*\n",
    "\n",
    "### Ensure that the tutorial works reliably\n",
    "\n",
    "One of your jobs as a tutor is to inspire the beginner's confidence.\n",
    "Confidence can only be built up layer by layer, but is easily shaken. It\n",
    "helps to maintain a friendly tone, as does consistent use of language,\n",
    "and a logical progression through the material. However, the single most\n",
    "important requirement is that **what you ask the beginner to do must\n",
    "work**. The learner needs to see that when they follow your directions,\n",
    "they will attain the results you promise.\n",
    "\n",
    "It's hard work to create a reliable experience, but that is what you\n",
    "must aspire to in creating a tutorial.\n",
    "\n",
    "### Ensure the user sees results immediately\n",
    "\n",
    "Your learner is probably doing new and strange things that they don't\n",
    "understand. Don't make them do too many before they see a result from\n",
    "their actions. As far as possible, the effect of every action should be\n",
    "clear to them as soon as possible. The relation of cause and effect\n",
    "should be evident. Finally, each result should be something that the\n",
    "user can see as meaningful.\n",
    "\n",
    "**Every step the learner follows should produce a comprehensible result,\n",
    "however small.**\n",
    "\n",
    "### Make your tutorial repeatable\n",
    "\n",
    "Unless you're very lucky, the users of your tutorial will have\n",
    "different levels of skill and understanding. They might also be using\n",
    "different tools and operating systems and you can't rely on them having\n",
    "the same resources or environment.\n",
    "\n",
    "This makes repeatable reliability extremely hard to achieve, and yet,\n",
    "**your tutorial should work for all users, every time**.\n",
    "\n",
    "You have no alternative but to test your tutorials regularly to make\n",
    "sure that they still work as expected.\n",
    "\n",
    "### Describe concrete steps, not abstract concepts\n",
    "\n",
    "**Tutorials are composed of concrete steps**, not abstract discussion.\n",
    "Be specific and particular, about actions and outcomes.\n",
    "\n",
    "Resist the temptation to introduce abstraction. All learning proceeds\n",
    "from the particular and concrete to the general and abstract. It's\n",
    "later, after a beginner has encountered multiple concrete examples that\n",
    "they are ready to see a pattern in them and seek an abstract account of\n",
    "what is happening - until that time, requiring the learner to handle\n",
    "levels of abstraction before they have even had a chance to grasp the\n",
    "concrete is confusing and places unnecessary burdens on them.\n",
    "\n",
    "It's hard to resist this temptation, because once we have grasped\n",
    "something, we rely on the power of abstraction to frame it to ourselves\n",
    "- and that's how we want to frame it to others. But it's simply not\n",
    "how learning or successful teaching works.\n",
    "\n",
    "### Offer only minimum, necessary, explanation\n",
    "\n",
    "**If the learner doesn't need an explanation in order to complete the\n",
    "tutorial, don't explain.**\n",
    "\n",
    "For example, it's enough to say something like: *We're using HTTPS\n",
    "because it's more secure.* There is a place for extended discussion and\n",
    "explanation of HTTPS, but not in a tutorial. Sometimes, even that much\n",
    "explanation is more than required.\n",
    "\n",
    "It can seem problematic that we are asking a user to do things, without\n",
    "much explanation why. In practice, for the learner, it rarely is. The\n",
    "learner is focused on following your directions and getting a result;\n",
    "their time for wanting to know more about the *why* of what they're\n",
    "doing will come later. By all means include links to further explanatory\n",
    "material, if you feel it's required, but try to resist the temptation\n",
    "to interrupt the flow of a tutorial by digressing into explanation.\n",
    "\n",
    "### Ignore options and alternatives\n",
    "\n",
    "Your job is to guide the learner to a successful conclusion. There may\n",
    "be many interesting diversions along the way (different options for the\n",
    "command you're using, different ways to use the API, different\n",
    "approaches to the task you're describing) - ignore them. **Your\n",
    "guidance needs to remain focused on what's required to reach the\n",
    "conclusion**, and everything else can be left for another time.\n",
    "\n",
    "Doing this helps keep your tutorial shorter and crisper, and saves both\n",
    "you and the reader from having to do extra cognitive work."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}