Fix #9: link templates to guide sections

dsa-ou · Mar 19, 2024 · f4ef43f · f4ef43f
1 parent 8a25a0e
commit f4ef43f
Show file tree

Hide file tree

Showing 3 changed files with 84 additions and 34 deletions.
diff --git a/src/docs/essays/template-data-structures.ipynb b/src/docs/essays/template-data-structures.ipynb
@@ -6,7 +6,8 @@
    "metadata": {},
    "source": [
     "This [algorithmic essay](https://dsa-ou.github.io/algoesup) template is for students of data structures and algorithms (DSA) courses. \n",
-    "For more details on how to use this template, see our [Writing Guide](https://dsa-ou.github.io/algoesup/writing).\n",
+    "Throughout the template, there are links to relevant sections of our \n",
+    "[Writing Guide](https://dsa-ou.github.io/algoesup/writing).\n",
     "Replace any text in italics by yours and delete this paragraph.\n",
     "\n",
     "# _Your essay's title_ \n",
@@ -19,7 +20,13 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "_The introduction explains what the essay is about, the problem you are solving, and what you assume the reader to know._"
+    "_The introduction explains what the essay is about, the problem you are solving, and what you assume the reader to know.\n",
+    "See our guidance on \n",
+    "[choosing a problem](https://dsa-ou.github.io/algoesup/writing/#problem),\n",
+    "[writing the text](https://dsa-ou.github.io/algoesup/writing/#text) and\n",
+    "[structuring the essay](https://dsa-ou.github.io/algoesup/writing/#structure).\n",
+    "This template follows the first structure in the guide.\n",
+    "You don't need to change the following code cells._"
    ]
   },
   {
@@ -44,6 +51,15 @@
     "from algoesup import test, time_cases, time_functions"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "_For information on what the following commands do, see our guide's sections on\n",
+    "[type checking](https://dsa-ou.github.io/algoesup/writing/#type-checking) and \n",
+    "[linting](https://dsa-ou.github.io/algoesup/writing/#linting) and remove this paragraph._"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -69,7 +85,8 @@
    "source": [
     "## 1 Tests\n",
     "\n",
-    "_This section describes and defines the tests you will use to check your solutions._ "
+    "_This section describes and defines the tests you will use to check your solutions.\n",
+    "See the [testing section](https://dsa-ou.github.io/algoesup/writing/#testing) of our guide._"
    ]
   },
   {
@@ -101,6 +118,9 @@
    "source": [
     "## 2 Algorithms\n",
     "\n",
+    "_This section outlines some algorithms that solve the problem.\n",
+    "See the [algorithms section](https://dsa-ou.github.io/algoesup/writing/#algorithms) of our guide._\n",
+    "\n",
     "### 2.1 _First algorithm name_\n",
     "\n",
     "_Describe your first strategy or approach._\n",
@@ -164,7 +184,8 @@
    "source": [
     "## 3 Code\n",
     "\n",
-    "_This section implements and tests the most promising algorithms._"
+    "_This section implements and tests only the most promising algorithms.\n",
+    "See the [code section](https://dsa-ou.github.io/algoesup/writing/#code) of our guide._"
    ]
   },
   {
@@ -226,7 +247,8 @@
    "source": [
     "## 4 Performance\n",
     "\n",
-    "_This section measures and compares the run-times of your implementations._"
+    "_This section measures and compares the run-times of your implementations,\n",
+    "so that you can check them against your earlier complexity analysis._"
    ]
   },
   {
@@ -236,7 +258,7 @@
    "source": [
     "### 4.1 Generating inputs\n",
     "\n",
-    "_Briefly describe your strategy and reasoning for generating the inputs._"
+    "_Briefly describe your strategy and reasoning for [generating the inputs](https://dsa-ou.github.io/algoesup/writing/#generating-inputs)._"
    ]
   },
   {
@@ -289,7 +311,10 @@
    "source": [
     "### 4.2 Best, normal and worst run-times\n",
     "\n",
-    "_State which solution will be timed with best-, normal-, and worst-case inputs._"
+    "_State which solutions(s) will be timed with best-, normal- or worst-case inputs.\n",
+    "See the [comparing cases](https://dsa-ou.github.io/algoesup/writing/#comparing-cases) \n",
+    "and [charting run-times](https://dsa-ou.github.io/algoesup/writing/#charting-run-times) \n",
+    "sections of our guide._"
    ]
   },
   {
@@ -318,7 +343,9 @@
     "deepnote_cell_type": "markdown"
    },
    "source": [
-    "_Analyse the results._"
+    "_Analyse the results. See the \n",
+    "[interpreting run-times](https://dsa-ou.github.io/algoesup/writing/#interpreting-run-times) \n",
+    "section of our guide._"
    ]
   },
   {
@@ -327,7 +354,10 @@
    "metadata": {},
    "source": [
     "### 4.3 Fastest and slowest algorithm\n",
-    "_Compare the run times of all your solutions for the same case._"
+    "_Compare the run times of all your solutions for the same case.\n",
+    "See the [comparing functions](https://dsa-ou.github.io/algoesup/writing/#comparing-functions) \n",
+    "and [charting run-times](https://dsa-ou.github.io/algoesup/writing/#charting-run-times) \n",
+    "sections of our guide._"
    ]
   },
   {
@@ -350,14 +380,12 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
-   "metadata": {
-    "cell_id": "5e4e66073e5948ada2769753e54aedb5",
-    "deepnote_cell_type": "markdown"
-   },
+   "metadata": {},
    "source": [
-    "_Analyse the results._"
+    "_Analyse the results. See the \n",
+    "[interpreting run-times](https://dsa-ou.github.io/algoesup/writing/#interpreting-run-times) \n",
+    "section of our guide._"
    ]
   },
   {
@@ -372,7 +400,10 @@
     "\n",
     "_Summarise your findings and conclude which solution is best._\n",
     "\n",
-    "_After completing a draft of your essay, read our [Feedback Guide](https://dsa-ou.github.io/algoesup/feedback) on how to ask for, give, and handle comments._"
+    "_After completing a draft of your essay, do a \n",
+    "[final check](https://dsa-ou.github.io/algoesup/writing/#final-check) and then \n",
+    "see the [feedback guide](https://dsa-ou.github.io/algoesup/feedback) \n",
+    "on how to ask for, give, and handle comments._"
    ]
   },
   {
@@ -381,7 +412,9 @@
    "source": [
     "## 6 Acknowledgements\n",
     "\n",
-    "_Credit those who helped you create the essay._"
+    "_Credit those who helped you create the essay.\n",
+    "See the [crediting feedback](https://dsa-ou.github.io/algoesup/feedback/#crediting-feedback  ) \n",
+    "section of our guide._"
    ]
   }
  ],

diff --git a/src/docs/essays/template-intro-programming.ipynb b/src/docs/essays/template-intro-programming.ipynb
@@ -1,15 +1,12 @@
 {
  "cells": [
   {
-   "attachments": {},
    "cell_type": "markdown",
-   "metadata": {
-    "cell_id": "7d5cdec1dd5543618a0bb661ad996a41",
-    "deepnote_cell_type": "markdown"
-   },
+   "metadata": {},
    "source": [
     "This [algorithmic essay](https://dsa-ou.github.io/algoesup) template is for students of introductory programming courses. \n",
-    "For more details on how to use this template, see our [Writing Guide](https://dsa-ou.github.io/algoesup/writing).\n",
+    "Throughout the template, there are links to relevant sections of our \n",
+    "[Writing Guide](https://dsa-ou.github.io/algoesup/writing).\n",
     "Replace any text in italics by yours and delete this paragraph.\n",
     "\n",
     "# _Your essay's title_ \n",
@@ -18,11 +15,16 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "_The introduction explains what the essay is about, the problem you are solving, and what you assume the reader to know._"
+    "_The introduction explains what the essay is about, the problem you are solving, and what you assume the reader to know.\n",
+    "See our guidance on \n",
+    "[choosing a problem](https://dsa-ou.github.io/algoesup/writing/#problem),\n",
+    "[writing the text](https://dsa-ou.github.io/algoesup/writing/#text) and\n",
+    "[structuring the essay](https://dsa-ou.github.io/algoesup/writing/#structure).\n",
+    "This template follows the second structure in the guide.\n",
+    "You don't need to change the following code cells._"
    ]
   },
   {
@@ -48,6 +50,14 @@
     "from algoesup import test, time_functions_int"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "_For information on what the following commands do, see our guide's section on\n",
+    "[linting](https://dsa-ou.github.io/algoesup/writing/#linting) and remove this paragraph._"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -62,16 +72,13 @@
    ]
   },
   {
-   "attachments": {},
    "cell_type": "markdown",
-   "metadata": {
-    "cell_id": "7b98ae4e4fa5493aa7cf662ca5d93db7",
-    "deepnote_cell_type": "markdown"
-   },
+   "metadata": {},
    "source": [
     "## 1 Tests\n",
     "\n",
-    "_This section describes and defines the tests you will use to check your solutions._ "
+    "_This section describes and defines the tests you will use to check your solutions.\n",
+    "See the [testing section](https://dsa-ou.github.io/algoesup/writing/#testing) of our guide._"
    ]
   },
   {
@@ -195,7 +202,10 @@
     "\n",
     "_Summarise your findings and conclude which solution is best._\n",
     "\n",
-    "_After completing a draft of your essay, read our [Feedback Guide](https://dsa-ou.github.io/algoesup/feedback) on how to ask for, give, and handle comments._"
+    "_After completing a draft of your essay, do a \n",
+    "[final check](https://dsa-ou.github.io/algoesup/writing/#final-check) and then \n",
+    "see the [feedback guide](https://dsa-ou.github.io/algoesup/feedback) \n",
+    "on how to ask for, give, and handle comments._"
    ]
   },
   {
@@ -204,7 +214,9 @@
    "source": [
     "## 5 Acknowledgements\n",
     "\n",
-    "_Credit those who helped you create the essay._"
+    "_Credit those who helped you create the essay.\n",
+    "See the [crediting feedback](https://dsa-ou.github.io/algoesup/feedback/#crediting-feedback  ) \n",
+    "section of our guide._"
    ]
   }
  ],

diff --git a/src/docs/writing.md b/src/docs/writing.md
@@ -108,9 +108,14 @@ If you didn't invent the problem, indicate its source, e.g. by providing a link
 or by writing something like "This is problem 4.5 in [book title] by [author]."
 
 ## Algorithms
-You should describe each algorithm succinctly, preferably *before* implementing it,
+You should choose at least two sufficiently different algorithms that solve the problem,
+and describe each one succinctly, preferably *before* implementing it,
 to make the code easier to understand for the reader.
 
+We recommend to not describe algorithms that are only slight variants of each other,
+as this is usually of little interest, and 
+to only include two algorithms in your first draft.
+
 If you're using solutions by others, e.g. by LeetCode users,
 acknowledge the original author and provide a link to their solution.
 If you have modified their solutions, state what you have changed and explain why.