docs/how_tos/example_how_to.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "55c4879d",
   "metadata": {},
   "source": [
    "# Quantum Prototype How-To\n",
    "\n",
    "How-to guides take the user through the steps required to solve a real-world problem.\n",
    "\n",
    "They are recipes, directions to achieve a specific end."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bc98f5cf",
   "metadata": {},
   "source": [
    "## How to write good how-to guides\n",
    "\n",
    "### Provide a series of steps\n",
    "\n",
    "**How-to guides must contain a list of steps, that need to be followed in order** (just like tutorials to). You don’t have to start at the very beginning, just at a reasonable starting point. How-to guides should be reliable, but they don’t need to have the cast-iron repeatability of a tutorial.\n",
    "\n",
    "### Focus on results\n",
    "\n",
    "**How-to guides must focus on achieving a practical goal.** Anything else is a distraction. As in tutorials, detailed explanations are out of place here.\n",
    "\n",
    "### Solve a particular problem\n",
    "\n",
    "**A how-to guide must address a specific question or problem:** How do I …?\n",
    "\n",
    "This is one way in which how-to guides are distinct from tutorials: when it comes to a how-to guide, the reader can be assumed to know what they should achieve, but don’t yet know how - whereas in the tutorial, you are responsible for deciding what things the reader needs to know about.\n",
    "\n",
    "### Don’t explain concepts\n",
    "\n",
    "**A how-to guide should not explain things.**  It’s not the place for discussions of that kind; they will simply get in the way of the action. If explanations are important, link to them.\n",
    "\n",
    "### Allow for some flexibility\n",
    "\n",
    "**A how-to guide should allow for slightly different ways of doing the same thing.** It needs just enough flexibility in it that the user can see how it will apply to slightly different examples from the one you describe, or understand how to adapt it to a slightly different system or configuration from the one you’re assuming. Don’t be so specific that the guide is useless for anything except the exact purpose you have in mind.\n",
    "\n",
    "### Leave things out\n",
    "\n",
    "**Practical usability is more valuable than completeness.** Tutorials need to be complete, end-to-end guides; how-to guides do not. They can start and end where it seems appropriate to you. They don’t need to mention everything that there is to mention either, just because it is related to the topic. A bloated how-to guide doesn’t help the user get speedily to their solution.\n",
    "\n",
    "### Name guides well\n",
    "\n",
    "**The title of a how-to document should tell the user exactly what it does.** How to create a class-based view is a good title. Creating a class-based view or worse, Class-based views, are not."
   ]
  }
 ],
 "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
}