differences for PR #40

introduction.md

@@ -6,7 +6,7 @@ exercises: 2
 
 :::::::::::::::::::::::::::::::::::::: questions
 
-- What is software documentation?
+- How do we provide information to users of our research software?
 - Why is documenting code useful for researchers?
 - What does well-documented software look like?
 
@@ -22,14 +22,24 @@ exercises: 2
 
 ## Why document code?
 
-No code is self-explanatory. It’s a tool we design, or, more often, a complex organism that develops as we use it, such as a library of functions used within a research team to perform certain kinds of analysis.
+No code is self-explanatory. It’s a tool we design, or, more often, a complex organism that develops as we use it, such as a library of functions used within a research team to perform certain kinds of analysis. To explain our code we must write **software documentation**.
 
-To explain our code we must write **software documentation**. These documents provide information about our  programs for everyone involved in its development, use, and future re-use. Documentation may consist of text, tips within a computer environment, and diagrams that guide the user in using a (potentially complex) software tool. It explained how the software works why it behaves the way it does.
+These documents **provide information** about our programs for everyone involved in its development, use, and future re-use. Documentation may consist of text, tips within a computer environment, and diagrams that guide the user in using a (potentially complex) software tool. It explained how the software works why it behaves the way it does.
 
 ## Why document software?
 
 It’s a common occurrence to get a software package, whether it’s written by ourselves, a colleague, or someone else, that’s near-impossible to use because it’s unclear what each function or tool does. Maybe we look at the source code itself, but we can’t make head-nor-tail of it. Maybe the only person who can use this software is the person who wrote it—unless you wrote it and forgot what you were thinking when you did!
 
+:::: challenge
+
+Discuss positive or negative experiences with using research software:
+
+- What documentation was available?
+- What challenges did you have picking up a new tool?
+- What useful software-related information do you often refer to in your research projects?
+
+::::
+
 ### Advantages of good documentation
 
 There are many advantages to writing guidance to go along with your research software. Software documentation helps yourself and others to use it successfully in the future and read your code ensuring that its value is sustained.
@@ -42,6 +52,16 @@ Writing a useful software package that is well-documented and can be reused in t
 
 In the long run, it can help you to develop your own software engineering practice by getting into the habit of reflecting on what the purpose of the software is and to articulate what each component or module is for.
 
+:::: challenge
+
+Discuss the benefits of writing documentation for your research software.
+
+- How will it help you and your work?
+- What benefits will these provide to your collaborators?
+- In what ways does documentation contribute to the wider research community?
+
+::::
+
 ## When should I write documentation?
 
 Now! Start writing and sharing documentation for your reseach code from the beginning of your project. This might include design notes, diagrams, or the various kinds of software documentation we'll discuss in this module. The best practice for modern, collaborative research involving digital methods and tools is to document your processes *early and often*. Not only will writing notes about your code help other people to read and use that code, it will clarify your thought process as you design your system, focussing your work on the important parts of the task at hand.
@@ -50,7 +70,7 @@ Keep in touch with other developers and users of the research code and make a no
 
 ## Examples
 
-Here are some examples of some code to perform some geometry. The first example could be improved in terms of its documentation and readability, while the second one is much clearer. Which one would you prefer to use?
+Here are some examples of some code to perform some geometry. The first example could be improved in terms of its documentation and readability, while the second one is much clearer.
 
 ### Example of no documentation
 
@@ -81,11 +101,21 @@ run <- function(x) {
 
 :::
 
+:::: challenge
+
+Read and evaluate this code.
+
+- Can you tell what the purpose of the function is?
+- What is the meaning of the variables?
+- Would you rely on this code in your research? Why, or why not?
+
+::::
+
 This is a function with a name that doesn't explain what the code will do. There are no comments or notes to explain what the author intended to achieve. The variable names don't clarify anything either: what does `x` mean in this context? Where would I go to find out more about `weird_num`? This is effectively a "magic" number that is arbitrarily stated but unexplained.
 
 The logic of the calculation is also... rather cryptic.
 
-Maybe the code works, maybe it doesn't (would you trust it?) but it could be made clearer and easier to maintain and modify in the future.
+Maybe the code works, maybe it doesn't but it could be made clearer and easier to maintain and modify in the future.
 
 ### Well-documented example
 
@@ -159,6 +189,16 @@ calculate_sine <- function(angle) {
 }
 ```
 
+:::: challenge
+
+Read and evaluate this code.
+
+- Can you tell what the purpose of the function is?
+- What is the meaning of the variables?
+- Which code would you prefer to use?
+
+::::
+
 :::
 
 This time, the function name is a verb that describes what the code will attempt to do. The description of the function is also written out clearly in a note for the user. There are comment lines (starting with `#`) that explain the mathematicalal method used. Each variable has a descriptive, human-readable name, making the code more intuitive to read. An existing library is used to calculate the factorial, which means we can look up the usage for the `factorial()` function elsewhere.

md5sum.txt

@@ -5,7 +5,7 @@
 "config.yaml" "3b1d16fd12463440e79d99b3ad2855c0" "site/built/config.yaml" "2024-08-16"
 "index.md" "568532bd1e8c470d82e70a56a5130136" "site/built/index.md" "2024-08-14"
 "links.md" "8184cf4149eafbf03ce8da8ff0778c14" "site/built/links.md" "2024-05-20"
-"episodes/introduction.md" "d7d10624b64f1f50252fdc94cc9e5ff5" "site/built/introduction.md" "2024-08-16"
+"episodes/introduction.md" "1530c5c98468d791a336bc37497643eb" "site/built/introduction.md" "2024-08-16"
 "episodes/readmes.md" "7f814493f5072a579424de3222583ebb" "site/built/readmes.md" "2024-07-22"
 "episodes/docstrings.md" "28d95c6f87a20ecb3ece5010a999f8b9" "site/built/docstrings.md" "2024-08-16"
 "episodes/readable.md" "1f80fef3634faac146f4d6d324a92a3b" "site/built/readable.md" "2024-08-16"