Drew changes

Author: alexsquires

content/good_practice/documentation.ipynb

@@ -4,13 +4,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Documentation\n",
+    "# Writing documentation\n",
     "\n",
     "prerequistes:\n",
     "- types \n",
     "- collections\n",
+    "- reading and finding documentation\n",
     "\n",
-    "Effective communication is essential to research: if no one can understand your work, you may as well have never have done it. Any code produced as part of your research also needs to communicated effectively, if for no other reason that _you_ need to understand what you were trying to do when you revisit your code, days, weeks or months after you originally wrote it. The cell below contains 'functional' code, but is not instantly recognisable as to what it is doing. In this section, we will work through this code, adding layers of simple 'documentation' to communicate what it is doing. \n",
+    "Effective communication is essential to learning and research: if no one can understand your work, you may as well have never have done it. Any code produced as part of your research also needs to communicated effectively, if for no other reason that _you_ need to understand what you were trying to do when you revisit your code, days, weeks or months after you originally wrote it. The cell below contains _functional_ code, but is not instantly recognisable as to what it is doing. In this section, we will work through this code, adding layers of simple 'documentation' to communicate what it is doing. \n",
     "\n",
     "See if you can work out what the code is doing before we write any documentation."
    ]
@@ -51,7 +52,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If you couldn't work it out, don't worry. Let's start communicating the code more effectivly by stating the problem we are trying to solve: the code below solves Bragg's law for an orthorombic crystal to determine the Bragg angle associated with a given miller plane. Perhaps the easiest thing we can do is re-write the code, with clearer variable names."
+    "If you couldn't work it out, don't worry. Let's start communicating the code more effectivly by stating the problem we are trying to solve: **the code below solves Bragg's law for an orthorombic crystal to determine the Bragg angle associated with a given miller plane.** Perhaps the easiest thing we can do is re-write the code, with clearer variable names."
    ]
   },
   {
@@ -94,7 +95,7 @@
    "source": [
     "While not exactly documentation, using descriptive variable names does improve the readability of the code. Anyone versed in crystallography would likely read the above code and be able to more quickly surmise what it is trying to achieve. That being said, we can be even more helpful buy using 'comments'.\n",
     "\n",
-    "Comments begin with a hash symbol '#' and will not be read as python in a code cell, for example:"
+    "Comments begin with a hash symbol `#` and will not be read as python in a code cell, for example:"
    ]
   },
   {
@@ -141,7 +142,7 @@
     "\n",
     "# calculate scattering angle of an miller plane in an orthorhombic Bravias lattice\n",
     "\n",
-    "# define miller indicies\n",
+    "# define miller indices\n",
     "\n",
     "h = 1\n",
     "k = 1\n",
@@ -173,7 +174,7 @@
    "source": [
     "Hopefully the above code is now straightforward to comprehend for anyone with an interest in either the mechanics of the code, or the scientific problem it attempts to solve. It is important to bear in mind that commenting should be used sparingly, and the context should be considered to avoid redundancy. Ultimately, we are trying to convey the function of the code, and not distract from that. Some points in the above text about possible redundancies, and contextual commenting:\n",
     "\n",
-    "- The first comment `# calculate scattering angle of an miller plane in an orthorhombic Bravias lattice` is redundent given the context of the code, i.e. in this jupyter book, we have already explained what we are trying to to do, but if this were a stand-alone script, a concise explanation of what the code does - such as this comment - is very helpful. Note this could also come from the name of the script or notebook.\n",
+    "- The first comment `# calculate scattering angle of an miller plane in an orthorhombic Bravias lattice` is redundant given the context of the code, i.e. in this jupyter book: we have already explained what we are trying to to do, but if this were a stand-alone script, a concise explanation of what the code does - such as this comment - is very helpful. Note this could also come from the name of the script or notebook.\n",
     "\n",
     "- Consider the line ```xray_wavelength = 1.5406 # wavelength of incident radition in Angstroms```. If it read ```xray_wavelength = 1.5406 # wavelength of incident radition``` this would be a redundant comment: the variable name conveys the same message as the comment itself. As scientists, however, it's imperative to convey the units we are working in, and so the addition of 'in Angstroms' confers meaning to the value. \n",
     "\n",
@@ -232,7 +233,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If it weren't for the fact the cell above produces the same ouptut as the cells in the previous section, you may be forgiven for thinking, on first glance, that this reformulation of the code might do something slightly different. This misconception could have been avoided using docstrings, which were breifly discussed in the functions section. We revisit the concept here, to emphasis that even though they are a non-essential part of the function (as shown by the functioning code above), they offer a great deal of clarity. The description of docstrings given in the function section is quoted below:\n",
+    "If it weren't for the fact the cell above produces the same ouptut as the cells in the previous section, you may be forgiven for thinking, on first glance, that this reformulation of the code might do something slightly different. This misconception could have been avoided using docstrings, which were breifly discussed in the functions section. We revisit the concept here, to emphasise that even though they are a non-essential part of the function (as shown by the functioning code above), they offer a great deal of clarity. The description of docstrings given in the function section is quoted below:\n",
     "\n",
     "> The docstring is an important (although not essential) component of any function. Describing the purpose of a function is valuable of many reasons, it helps to clarify what the function will do, it offers guidence for others on how to use the function, and it acts to remind future you why it is that you have a particular function and what is does. You may read this last point and roll your eyes, however I promise you that code you write today will not stay present in your memory forever.\n",
     "\n",
@@ -336,12 +337,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This is a really helpful trick that can be applied to any python function, should you forget what it does/what arguemnts are required, i.e."
+    "This is a really helpful trick that can be applied to any python function, should you forget what it does/what arguments are required, i.e."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 61,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [
     {
@@ -405,6 +406,13 @@
     "# note numpy does not use the 'Google' style docstring.\n",
     "ones?"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {