Merge pull request #166 from coding-for-reproducible-research/proof_reading

liamjberrisford · web-flow · commit 148bee154866 · 2024-10-08T12:58:17.000+01:00
Proof reading for the Software Development Best Practice Couse
diff --git a/individual_modules/section_landing_pages/software_development_best_practice.md b/individual_modules/section_landing_pages/software_development_best_practice.md
@@ -2,6 +2,8 @@
 
 ## Overview 
 
+The course is designed to be interactive, though all related resources are available on the following pages.
+
 This course comprises two two-hour sessions. The course is designed to be interactive and so will be delivered within a seminar style with live demonstrations and activities. We have allowed plenty of time for discussion and questions throughout - please simply shout out any questions/comments you have or raise your physical/virtual hand. We will also have a short comfort break approximately three quarters of the way through the session. We will also share the slides and there is a list of resources on the website for this course.
 
 ## Course Objectives 
diff --git a/individual_modules/software_development_best_practices/collaboration.ipynb b/individual_modules/software_development_best_practices/collaboration.ipynb
@@ -15,7 +15,7 @@
     "\n",
     "## Learning Objectives\n",
     "- Understand the key elements of effective collaboration in large projects\n",
-    "- Implement Agile methodology to maintain flexibility and response efficiently to changes\n",
+    "- Implement Agile methodology to maintain flexibility and respond efficiently to changes\n",
     "- Utilize version control tools like Git and GitHub for managing changes and tracking project tasks\n",
     "- Establish effective communication channels and strategies for collaborative projects\n",
     "- Recognize and address challenges encountered during collaboration \n",
diff --git a/individual_modules/software_development_best_practices/data_management.ipynb b/individual_modules/software_development_best_practices/data_management.ipynb
@@ -147,13 +147,13 @@
     {
      "data": {
       "text/html": [
-       "<div id=\"fUcHejYHRoke\" data-shufflequestions=\"False\"\n",
+       "<div id=\"NwqduCfeBStR\" data-shufflequestions=\"False\"\n",
        "               data-shuffleanswers=\"True\"\n",
        "               data-preserveresponses=\"false\"\n",
        "               data-numquestions=\"1000000\"\n",
        "               data-maxwidth=\"600\"\n",
        "               style=\"border-radius: 10px; text-align: left\"> <style>\n",
-       "#fUcHejYHRoke {\n",
+       "#NwqduCfeBStR {\n",
        "   --jq-multiple-choice-bg: #6f78ffff;\n",
        "   --jq-mc-button-bg: #fafafa;\n",
        "   --jq-mc-button-border: #e0e0e0e0;\n",
@@ -335,7 +335,7 @@
     {
      "data": {
       "application/javascript": [
-       "var questionsfUcHejYHRoke=[\n",
+       "var questionsNwqduCfeBStR=[\n",
        "    {\n",
        "        \"question\": \"What is the purpose of a Data Management Plan (DMP)?\",\n",
        "        \"type\": \"many_choice\",\n",
@@ -393,7 +393,7 @@
        "        \"type\": \"many_choice\",\n",
        "        \"answers\": [\n",
        "            {\n",
-       "                \"answer\": \"It provides financial details of the project.\",\n",
+       "                \"answer\": \"It provides financial details of the project\",\n",
        "                \"correct\": false,\n",
        "                \"feedback\": \"Incorrect\"\n",
        "            },\n",
@@ -1163,8 +1163,8 @@
        "           Someone more knowledgeable could make this better ;-) */\n",
        "\n",
        "        function try_show() {\n",
-       "          if(document.getElementById(\"fUcHejYHRoke\")) {\n",
-       "            show_questions(questionsfUcHejYHRoke,  fUcHejYHRoke); \n",
+       "          if(document.getElementById(\"NwqduCfeBStR\")) {\n",
+       "            show_questions(questionsNwqduCfeBStR,  NwqduCfeBStR); \n",
        "          } else {\n",
        "             setTimeout(try_show, 200);\n",
        "          }\n",
@@ -1173,8 +1173,8 @@
        "        {\n",
        "        // console.log(element);\n",
        "\n",
-       "        //console.log(\"fUcHejYHRoke\");\n",
-       "        // console.log(document.getElementById(\"fUcHejYHRoke\"));\n",
+       "        //console.log(\"NwqduCfeBStR\");\n",
+       "        // console.log(document.getElementById(\"NwqduCfeBStR\"));\n",
        "\n",
        "        try_show();\n",
        "        }\n",
diff --git a/individual_modules/software_development_best_practices/problem_solving.ipynb b/individual_modules/software_development_best_practices/problem_solving.ipynb
@@ -23,7 +23,7 @@
     "\n",
     "## Exercise\n",
     "\n",
-    "The following narrative describes how two researchers, Sam and Charlie, have got satrted on their research problem. After reading the passage, given what we have discussed so far what are some of the potential processes they could ahve followed to stop them from having to rewrite the code?\n",
+    "The following narrative describes how two researchers, Sam and Charlie, have got started on their research problem. After reading the passage, given what we have discussed so far, what are some of the potential processes they could have followed to stop them from having to rewrite the code?\n",
     "\n",
     "> Sam wants to train a model to predict whether someone has a certain medical condition - they have clinical data, including diagnoses of the condition. Sam is collaborating with Charlie, and they have a high-level chat about the project, discussing what they would like to get out of the model. Sam is keen to get started so fires up the computer and begins writing code. After some time, Charlie asks Sam to share the uncertainties of the current model predictions - Sam does not have this information. Together, Sam and Charlie make changes to the code. To enable uncertainties to be calculated, they end up having to rewrite a significant amount of the code. Following this, they are stuck with what to do next.\n",
     "\n",
diff --git a/individual_modules/software_development_best_practices/questions/summary_collaboration.json b/individual_modules/software_development_best_practices/questions/summary_collaboration.json
@@ -56,7 +56,7 @@
         "type": "many_choice",
         "answers": [
             {
-                "answer": "Avoiding he use of version control",
+                "answer": "Avoiding the use of version control",
                 "correct": false,
                 "feedback": "Incorrect"
             },
diff --git a/individual_modules/software_development_best_practices/questions/summary_dmp.json b/individual_modules/software_development_best_practices/questions/summary_dmp.json
@@ -56,7 +56,7 @@
         "type": "many_choice",
         "answers": [
             {
-                "answer": "It provides financial details of the project.",
+                "answer": "It provides financial details of the project",
                 "correct": false,
                 "feedback": "Incorrect"
             },
diff --git a/individual_modules/software_development_best_practices/questions/summary_documentation.json b/individual_modules/software_development_best_practices/questions/summary_documentation.json
@@ -40,7 +40,7 @@
                 "feedback": "Correct"
             },
             {
-                "answer": "to avoid using version control systems",
+                "answer": "To avoid using version control systems",
                 "correct": false,
                 "feedback": "Incorrect"
             },
@@ -71,7 +71,7 @@
                 "feedback": "Incorrect"
             },
             {
-                "answer": "renaming functions to clearly indicate their purpose",
+                "answer": "Renaming functions to clearly indicate their purpose",
                 "correct": false,
                 "feedback": "Incorrect"
             }
diff --git a/individual_modules/software_development_best_practices/questions/summary_problem_solving.json b/individual_modules/software_development_best_practices/questions/summary_problem_solving.json
@@ -9,7 +9,7 @@
                 "feedback": "Correct"
             },
             {
-                "answer": "to combine multiple solution into one",
+                "answer": "To combine multiple solution into one",
                 "correct": false,
                 "feedback": "Incorrect"
             },
@@ -30,12 +30,12 @@
         "type": "many_choice",
         "answers": [
             {
-                "answer": "The software should provide the uncertainity of a prediction",
+                "answer": "The software should provide the uncertainty of a prediction",
                 "correct": true,
                 "feedback": "Correct"
             },
             {
-                "answer": "The software should make a predicition in less than a minute",
+                "answer": "The software should make a prediction in less than a minute",
                 "correct": false,
                 "feedback": "Incorrect"
             },
diff --git a/individual_modules/software_development_best_practices/questions/summary_reproducibility.json b/individual_modules/software_development_best_practices/questions/summary_reproducibility.json
@@ -9,7 +9,7 @@
                 "feedback": "Incorrect"
             },
             {
-                "answer": "To ensure that research results can be verfiied and reproduced by others",
+                "answer": "To ensure that research results can be verified and reproduced by others",
                 "correct": true,
                 "feedback": "Correct"
             },
@@ -30,17 +30,17 @@
         "type": "many_choice",
         "answers": [
             {
-                "answer": "Decreased credibility of research findings.",
+                "answer": "Decreased credibility of research findings",
                 "correct": false,
                 "feedback": "Incorrect"
             },
             {
-                "answer": "Reduced citations for open access articles.",
+                "answer": "Reduced citations for open access articles",
                 "correct": false,
                 "feedback": "Incorrect"
             },
             {
-                "answer": "Enhanced rate of research progression.",
+                "answer": "Enhanced rate of research progression",
                 "correct": true,
                 "feedback": "Correct"
             },
@@ -56,7 +56,7 @@
         "type": "many_choice",
         "answers": [
             {
-                "answer": "To lengthen the research process.",
+                "answer": "To lengthen the research process",
                 "correct": false,
                 "feedback": "Incorrect"
             },
diff --git a/individual_modules/software_development_best_practices/questions/summary_testing.json b/individual_modules/software_development_best_practices/questions/summary_testing.json
@@ -56,12 +56,12 @@
         "type": "many_choice",
         "answers": [
             {
-                "answer": "Requirements that define what the software should do.",
+                "answer": "Requirements that define what the software should do",
                 "correct": true,
                 "feedback": "Correct"
             },
             {
-                "answer": "Requirements that define how the software should behave.",
+                "answer": "Requirements that define how the software should behave",
                 "correct": false,
                 "feedback": "Incorrect"
             },
diff --git a/individual_modules/software_development_best_practices/questions/summary_version_control.json b/individual_modules/software_development_best_practices/questions/summary_version_control.json
@@ -56,7 +56,7 @@
         "type": "many_choice",
         "answers": [
             {
-                "answer": "It increases the sotrage space used",
+                "answer": "It increases the storage space used",
                 "correct": false,
                 "feedback": "Incorrect"
             },
diff --git a/individual_modules/software_development_best_practices/questions/summary_virtual_environments.json b/individual_modules/software_development_best_practices/questions/summary_virtual_environments.json
@@ -35,7 +35,7 @@
                 "feedback": "Incorrect"
             },
             {
-                "answer": "To create a separate environment for each project to manage dependencies and avoid conflicts.",
+                "answer": "To create a separate environment for each project to manage dependencies and avoid conflicts",
                 "correct": true,
                 "feedback": "Correct"
             },
diff --git a/individual_modules/software_development_best_practices/readable_code_and_documentation.ipynb b/individual_modules/software_development_best_practices/readable_code_and_documentation.ipynb
@@ -22,16 +22,16 @@
     "## Introduction to Readable Cdoe \n",
     "Readable code is essential for effective programming and maintenance. It makes the code easier to understand, debug, extend, and share with others. These notes will guide you through understanding what makes code readable and how to apply these principles in practice.\n",
     "\n",
-    "### Impoving Code Readability\n",
+    "### Improving Code Readability\n",
     "\n",
-    "For this exercise please take a look at the following Python code snippet. Be aware that you do not need to know Python (or even have any programming expereince) to engage with this exercise. Start by traing to ascertain what the code does. What do you think this code does? The answer is below. \n",
+    "For this exercise please take a look at the following Python code snippet. Be aware that you do not need to know Python (or even have any programming experience) to engage with this exercise. Start by trying to ascertain what the code does. What do you think this code does? The answer is below. \n",
     "\n",
     "```{admonition} Click to reveal what the code snippet does!\n",
     ":class: tip, dropdown\n",
-    "The code print the Fibonacci sequence up to the required sentence length.\n",
+    "The code prints the Fibonacci sequence up to the required sentence length.\n",
     "```\n",
     "\n",
-    "Given knowing what the code actully does, how would you improve the code's readability?\n",
+    "Knowing what the code actually does, how would you improve the code's readability?\n",
     "\n",
     "```Python\n",
     "def my_f(arg1):\n",
@@ -120,7 +120,7 @@
     "- **Naming Conventions**: Use logical and descriptive naming conventions for functions, variables, and classes. Effective names can communicate the purpose of a code element, reducing the need for additional comments.\n",
     "- **Whitespace Usage**: Employ whitespace strategically to separate and emphasize related code blocks, enhancing the readability.\n",
     "- **Line Length**: Keep line lengths short to avoid horizontal scrolling, which can be disruptive and hinder code readability.\n",
-    "- **Style Guides and Formatters**: Utilize style guides (e.g., PEP8 for Python) and tools like code formatters (e.g., Black for Python) to maintain consistent formatting automatically.\n",
+    "- **Style Guides and Formatters**: Utilize style guides (e.g. PEP8 for Python) and tools like code formatters (e.g. Black for Python) to maintain consistent formatting automatically.\n",
     "#### Documentation \n",
     "- **Concise and Constructive**: In-code documentation should be concise yet comprehensive, providing clear explanations of the functionality.\n",
     "- **Explain Complex Aspects**: Documentation should clarify complex parts of the code and explain the rationale behind specific design decisions, rather than just reiterating what the code does.\n",
@@ -142,18 +142,18 @@
     "\n",
     "- **Conceptual Documentation**: This type of documentation offers a high-level overview of the software, covering its requirements, design specifications, and architecture. It's essential for giving users and developers a broad understanding of the software's purpose and structure.\n",
     "- **Hands-On Documentation**: Includes practical guides such as tutorials and user manuals that help new users start using the software. This documentation is instrumental in lowering the entry barrier for new users and contributors.\n",
-    "- **Reference Documentation**: Provides detailed descriptions of the software’s functionality and implementation details. This is often integrated directly into the code through comments and is invaluable for those who need to work with the codebase intimately.\n",
+    "- **Reference Documentation**: Provides detailed descriptions of the software’s functionality and implementation details. This is often integrated directly into the code through comments and is invaluable for those who need to work intimately with the codebase.\n",
     "\n",
     "#### Understanding the Audience \n",
     "\n",
-    "Different documentation types serve different audiences. The audience for a piece of software can range from end-users to developers and may vary especially in the context of research software, where these roles can overlap:\n",
+    "Different documentation types serve different audiences. The audience for a piece of software can range from end-users to developers and may vary, especially in the context of research software where these roles can overlap:\n",
     "\n",
     "- **User Documentation**: Aimed at those who will use the software, focusing on how to use its features.\n",
     "- **Developer Documentation**: Aimed at those who will develop or maintain the software, focusing on how the software is built and how to contribute to its development.\n",
     "\n",
     "#### Planning Documentation\n",
     "\n",
-    "Effective documentation requires careful planning, ideally starting before the software development begins. Some key aspects to consider when developing documentation includes:\n",
+    "Effective documentation requires careful planning, ideally starting before the software development begins. Some key aspects to consider when developing documentation include:\n",
     "\n",
     "- **Early Planning**: Think about the types of documentation needed from the start of the project. This foresight can influence design decisions and software architecture.\n",
     "- **Motivation and Goals**: Consider why the documentation is being created. Is it to increase impact, facilitate collaboration, or ensure citation? Understanding these goals can help tailor the documentation to meet these ends.\n",
diff --git a/individual_modules/software_development_best_practices/software_development_life_cycle.ipynb b/individual_modules/software_development_best_practices/software_development_life_cycle.ipynb
@@ -91,7 +91,7 @@
    "source": [
     "## Agile Development Tools and Techniques \n",
     "\n",
-    "Agile development tools and techniques that are beneficial not only in team settings but also for individuals working alone. Agile methodologies, including Scrum, Kanban, and Lean, offer a diverse array of tools and techniques designed to enhance planning, communication, and continuous improvement in software development projects. While these tools are typically associated with team dynamics, many can be adapted effectively for solo work.\n",
+    "Agile development tools and techniques are beneficial not only in team settings but also for individuals working alone. Agile methodologies, including Scrum, Kanban, and Lean, offer a diverse array of tools and techniques designed to enhance planning, communication, and continuous improvement in software development projects. While these tools are typically associated with team dynamics, many can be adapted effectively for solo work.\n",
     "\n",
     "Here are some key Agile tools and techniques that you might find useful in your day-to-day activities, whether working alone or in a team:\n",
     "\n",
diff --git a/individual_modules/software_development_best_practices/testing.ipynb b/individual_modules/software_development_best_practices/testing.ipynb
@@ -15,7 +15,7 @@
     "## Learning Objectives\n",
     "- Understand the purpose and importance of testing in software development\n",
     "- Identify the benefits of implementing tests in your code\n",
-    "- Differentiate between functional and on-functional requirements\n",
+    "- Differentiate between functional and non-functional requirements\n",
     "- Apply different testing strategies, including unit testing and integration testing\n",
     "- Develop and automate tests using tools like `pytest`\n",
     "\n",
@@ -54,8 +54,8 @@
     "\n",
     "### Test Cases to Consider\n",
     "- **Correctness**: Ensure the function returns a list of integers.\n",
-    "- **Sequence Accuracy**: Verify that the sequence length is correct and each integer follows the Fibonacci rule (i.e., each number is the sum of the two preceding numbers).\n",
-    "- **Edge Cases**: Test minimum sequence length and handle invalid inputs (e.g., sequence lengths less than 3).\n",
+    "- **Sequence Accuracy**: Verify that the sequence length is correct, and each integer follows the Fibonacci rule (i.e. each number is the sum of the two preceding numbers).\n",
+    "- **Edge Cases**: Test minimum sequence length and handle invalid inputs (e.g. sequence lengths less than 3).\n",
     "\n",
     "### Exercise Code "
    ]
diff --git a/individual_modules/software_development_best_practices/version_control.ipynb b/individual_modules/software_development_best_practices/version_control.ipynb
@@ -15,12 +15,12 @@
     "\n",
     "## Learning Objectives \n",
     "- Understand the importance of version control in managing file changes and collaboration\n",
-    "- Differentiate between git and GitHub and their respective roles\n",
+    "- Differentiate between Git and GitHub and their respective roles\n",
     "- Execute a basic Git workflow, including creating a repository, cloning, modifying files, and pushing changes\n",
     "- Identify alternatives to GitHub and their features\n",
-    "- use Git commands to manage and track changes in a project effectively\n",
+    "- Use Git commands to manage and track changes in a project effectively\n",
     "\n",
-    "Version control is an essential process for managing file changes over time, particularly in software development and document management. As part of Coding for Reproducible Research has a dedicated course to [Git and Version Control avaliable](../section_landing_pages/introduction_to_version_control.md)\n",
+    "Version control is an essential process for managing file changes over time, particularly in software development and document management. The Coding for Reproducible Research initiative offers a dedicated course covering [Git and Version Control.](../section_landing_pages/introduction_to_version_control.md)\n",
     "\n",
     "## Introduction to Version Control\n",
     "Version control allows us to track changes in files over time and revert to earlier versions when needed. It serves multiple purposes:\n",
diff --git a/individual_modules/software_development_best_practices/virtual_environments_dependency_managers.ipynb b/individual_modules/software_development_best_practices/virtual_environments_dependency_managers.ipynb

Original file line number	Diff line number	Diff line change
`@@ -56,7 +56,7 @@`
`56`	`56`	`"type": "many_choice",`
`57`	`57`	`"answers": [`
`58`	`58`	`{`
`59`		`- "answer": "Avoiding he use of version control",`
	`59`	`+ "answer": "Avoiding the use of version control",`
`60`	`60`	`"correct": false,`
`61`	`61`	`"feedback": "Incorrect"`
`62`	`62`	`},`
Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,7 @@`
`40`	`40`	`"feedback": "Correct"`
`41`	`41`	`},`
`42`	`42`	`{`
`43`		`- "answer": "to avoid using version control systems",`
	`43`	`+ "answer": "To avoid using version control systems",`
`44`	`44`	`"correct": false,`
`45`	`45`	`"feedback": "Incorrect"`
`46`	`46`	`},`
`@@ -71,7 +71,7 @@`
`71`	`71`	`"feedback": "Incorrect"`
`72`	`72`	`},`
`73`	`73`	`{`
`74`		`- "answer": "renaming functions to clearly indicate their purpose",`
	`74`	`+ "answer": "Renaming functions to clearly indicate their purpose",`
`75`	`75`	`"correct": false,`
`76`	`76`	`"feedback": "Incorrect"`
`77`	`77`	`}`