more best practices

nbs/tutorials/best_practices.ipynb

@@ -68,7 +68,7 @@
    "id": "e6f017dc",
    "metadata": {},
    "source": [
-    "<a href=\"https://documentation.divio.com/_images/overview.png\">![](https://documentation.divio.com/_images/overview.png){.rounded  alt=\"A 2x2 matrix, from top-left to bottom-right, 'Tutorials (learning-oriented)', 'How-to guides (problem-oriented)', 'Explanation (understanding-oriented), and 'Reference (information-oriented)'. Horizontal axis reads 'Most useful when we're studying' on the left, and 'Most useful when we're working' on the right. Vertical axis reads 'Practical steps' on top, and 'Theoretical knowledge' below.\"}</a>"
+    "<a href=\"/images/divio-overview.webp\">![](/images/divio-overview.webp){.rounded  alt=\"A 2x2 matrix, from top-left to bottom-right, 'Tutorials (learning-oriented)', 'How-to guides (problem-oriented)', 'Explanation (understanding-oriented), and 'Reference (information-oriented)'. Horizontal axis reads 'Most useful when we're studying' on the left, and 'Most useful when we're working' on the right. Vertical axis reads 'Practical steps' on top, and 'Theoretical knowledge' below.\"}</a>"
    ]
   },
   {
@@ -304,6 +304,28 @@
     ":::"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "4c625957",
+   "metadata": {},
+   "source": [
+    "## Make code cells short, and demonstrate them immediately"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "728b6c81",
+   "metadata": {},
+   "source": [
+    "In notebooks, do not create long functions and classes with comments interspersed throughout them. Instead, split your code up into small separate cells with explanations and working examples after each. This lets the user understand how each part works and experiment with them straight away. It also helps you during development because you can explore the behavior of every part of your code interactively.\n",
+    "\n",
+    "In non-notebook coding, the documentation, tests, code, and examples are all separate. This is not the case with nbdev. Take advantage of this by keeping all of these things as close together as possible. This is helpful both for exploration and for documentation.\n",
+    "\n",
+    "For example, consider the section of the Claudette source notebook for [implementing image support](https://claudette.answer.ai/core.html#images). The section immediately imports an image and displays it, showing how to work with a file format. It then creates a number of helper functions, describes and demonstrates them, and finally puts it all together to show how to use the complete feature in practice with real inputs and outputs running directly in the notebook.\n",
+    "\n",
+    "In order to avoid long class definitions caused by many methods, consider using fastcore's `patch` decorator to implement each method separately, and immediately document, demonstrate, and test it."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "f967dffc",