Add discussions and challenges

episodes/cli.md

@@ -22,15 +22,15 @@ exercises: 2
 
 ## Command line interfaces
 
-A command-line interface, usually abbreviated to CLI, is a terminal or prompt that accepts text input that instructs a computer what to do. They are used to start programs and perform actions within the computer's operating system.
+A command-line interface, usually abbreviated to <abbr title="Command-line interface">CLI</abbr>, is a terminal or prompt that accepts text input that instructs a computer what to do. They are used to start programs and perform actions within the computer's operating system.
 
 In this section, we'll introduce the concept of providing a command-line interface to our research code to make it easier to use and provide a well-documented "entry point" to our software.
 
 ### Advantages of CLIs for research tools
 
 Command lines are a way of interacting with a digital system that go back to the early history of computing. They might seem old-fashioned because typing out commands means that there is no graphical component. It may seem restrictive because your mouse isn't used, but terminals have a lot of power because we can formulate our instructions to the computer by writing commands. We have a direct line to control our computer's operating system.
 
-It's a great way to talk to your computer because you can record the commands that you've run to provide a documented history of a research process. (We could record a video screen capture of your working procedure, but that's much less efficient.)
+It's a great way to "talk" to your computer because you can record the commands that you've run to provide a documented history of a research process. (We could record a video screen capture of your working procedure, but that's much less efficient.)
 
 Terminals are more efficient for running repetitive tasks and provide extra functionality for advanced users. They are an cost-effective way to provide a user interface for research software, as research teams often lack the resources and know-how to produce sophisticated graphical user interfaces.
 
@@ -245,6 +245,29 @@ The output is a description of the `ls` command, instructions for using it, and
 
 :::
 
+::::::::::::::::::::::::::::::::::::: challenge
+
+Try the command line statements described above.
+
+- How would you seek further help if you encounter an error?
+- What response does the terminal provide? Is this what you expect?
+
+:::::::::::::::::::::::::::::::::::::
+
+## CLIs in R
+
+This rest of this episode is focussed on the Python programming language.
+
+R, while a powerful statistical computing language, doesn't have a built-in module specifically designed for creating <abbr title="Command-line interfaces">CLIs</abbr>. Unlike Python, this means that you'll need to use external packages or write your own functions to handle command-line arguments and options.
+
+However, there are several packages that can help you create to CLIs in R:
+
+- [optparse](https://trevorldavis.com/R/optparse/dev/)
+- [cli](https://cli.r-lib.org/)
+- [Rapp](https://github.com/r-lib/Rapp)
+
+These packages create <abbr title="Command-line interfaces">CLIs</abbr> for your R scripts, making them easier to distribute for others to use.
+
 ## CLIs in Python
 
 We can add a command-line interface to our Python code using the methods and tools that are included in the Python programming language.

episodes/contributors.md

@@ -21,14 +21,32 @@ exercises: 2
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
-## Introduction
+## Collaborative research software development
 
-Most research software is written in a collaborative manner, involving multiple specialists from within a team or from multiple institutions. For the long-term health of a software package, it’s important to encourage potential contributors to get in touch and feel welcome to take part. Useful research software can take on a life of its own. For more information on planning the development of research software and project governance, see Module 1a.
+Often, in today's research environment, much analytics software is written in a **collaborative manner**, involving multiple specialists from within a team, or from multiple institutions. For the long-term health of a software package, it’s important to encourage potential contributors to get in touch and feel welcome to take part. Useful research software can take on a life of its own.
+
+::::::::::::::::::::::::::::::::::::: callout
+
+## Research software project management
+
+For more information on planning the development of research software and project governance, see Module 1a.
+
+:::::::::::::::::::::::::::::::::::::
 
 It’s often published using an open source licence, which means that all the code is publicly available and may be used and modified by anyone, within certain conditions (see module 1b to learn more about software licensing.)
 
 There's a lot more creating and managing a sustainable community aorund a research software project, but having a central piece of documentation for contributors is a great start!
 
+::::::::::::::::::::::::::::::::::::: discussion
+
+Consider these questions amongst the group:
+
+- How can we effectively foster a collaborative environment for research software development?
+- How can barriers to participation be removed for a diverse range of individuals and institutions?
+- What strategies can be implemented to ensure that all contributors feel valued and included?
+
+:::::::::::::::::::::::::::::::::::::
+
 ## Contribution guides
 
 Contribution guidelines help users and understand how they can help to improve the software, whether that’s by submitting bug reports, suggesting new features, or writing better code and documentation. All of these aspects are vital to produce reusable research software.
@@ -39,9 +57,19 @@ It’s important to explain how the project is managed so the process for evalua
 
 Contribution guides will save you time in the long run, because it provides an on-ramp for people to get involved, prevents them from getting confused, and reduces the amount of incorrectly-submitted bug reports or requests for change, etc.
 
+::::::::::::::::::::::::::::::::::::: discussion
+
+Discuss these issues amongst the group:
+
+- What essential components should be included in a comprehensive documentation for research software contributors?
+- How can we make onboarding new contributors a smooth and welcoming process, ensuring they have the necessary information and support to be successful?
+- How can we balance the need for clear guidelines with the desire to encourage creativity and innovation?
+
+:::::::::::::::::::::::::::::::::::::
+
 ### How to write contributor guidance
 
-The stanard practice for authoring a contribution guide for a software project is to create a file called `CONTRIBUTING.md` in the root folder of your project. This is a Markdown file that introduces new people to the project. It lets people know the ways they can take part in the research software project and what to do to get involved.
+The standard practice for authoring a contribution guide for a software project is to create a file called `CONTRIBUTING.md` in the root folder of your project. This is a Markdown file that introduces new people to the project. It lets people know the ways they can take part in the research software project and what to do to get involved.
 
 The specific contents of this file depend upon the kind of research project, but some useful information to provide typically includes:
 
@@ -104,6 +132,15 @@ Many projects following programming standards to manage code quality. A coding s
 
 This might include guidance and advice, or more strict rules as standards that are checked by a code linter. A code linter is an analysis tool that inspects code and checks for common errors and problems, producing a report for the developer to read and act upon. Common coding style standards include the PEP 8 style guide for the Python programming language and the tidyverse style guide in the R statistical language.
 
+::::::::::::::::::::::::::::::::::::: discussion
+
+Discuss these issues as a group:
+
+- Why are coding conventions important for collaborative research projects?
+- How can we establish and enforce coding style guidelines that promote consistency and readability?
+
+:::::::::::::::::::::::::::::::::::::
+
 ::::::::::::::::::::::::::::::::::::: keypoints 
 
 - **Encourage collaboration:** There are **many ways to contribute** to a research software project, including bug reoprts, feature suggests, design discussions, documentation, and software engineering.

episodes/sites.md

@@ -22,7 +22,7 @@ exercises: 2
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
-## Introduction
+## Documentation websites
 
 A documentation website is a user guide and reference manual for a library of research code. Up to now, we've looked at ways to put helpful notes in our code, but now we'll learn how to write a longer, more complete guide to the research tools you create.
 
@@ -34,25 +34,44 @@ To get an idea of this, here are some links documentation websites for widely-us
 - [ggplot2](https://ggplot2.tidyverse.org/index.html) is a plotting package for the R statistical language.
 - [scikit-learn](https://scikit-learn.org/stable/user_guide.html) is a machine learning library for the Python programming language.
 
+::::::::::::::::::::::::::::::::::::: discussion
+
+Evaluate these documentation sites.
+
+- What do you like about them?
+- How approachable are they as a new user?
+- What do you find difficult to understand in this material?
+
+:::::::::::::::::::::::::::::::::::::
+
+## Why create a website?
+
+There are many advantages to building a documentation site to provide a information-rich resource for researchers who use your code at institutions all around the world.
+
 ### Advantages
 
-There are many advantages to building a documentation site to provide a information-rich resource for researchers who use your code at institutions all around the world. These sites can work as hubs for collaboration, sharing the latest updates, and encouraging people to take up your system and get involved in improving it. The effort of setting one up will be rewarded in the long run because you will have created a valuable asset that will foster collaboration and knowledge sharing in your research community.
+These sites can work as hubs for collaboration, sharing the latest updates, and encouraging people to take up your system and get involved in improving it. The effort of setting one up will be rewarded in the long run because you will have created a valuable asset that will foster collaboration and knowledge sharing in your research community.
 
 A key foundation stone of modern digital research practices is the ability to replicate results by reproducing analysis workflows.  Clear, thorough documentation of the research code ensures that researchers can repeat processes and verify results and other people's outputs.
 
-Documementation sites are really useful for introducing new users to your software. It makes it much easier and faster for new users to get started using your software to boost their research. It's one of the most effective ways to create a user base that has a sophisticated understanding of the research code, which is essential for them to adapt it to the complex problems that often raise in research contexts.
+Documentation sites are really useful for introducing new users to your software. It makes it much easier and faster for new users to get started using your software to boost their research. It's one of the most effective ways to create a user base that has a sophisticated understanding of the research code, which is essential for them to adapt it to the complex problems that often raise in research contexts.
 
 They're also a valuable resource for your existing user base, enabling them to look up reference material or search the manual to find new capabilities they weren't aware of before. This will increase the potential for your software to accellerate the productivity of other research teams and boost scientific progress.
 
 ### When to use one
 
-Although the advantages are numerous, not all software packages require a comprehensive documentation website. However, for any code project that is growing in the number of collaborators, users, and technicala complexity, consider coordinating the team to write one as soon as possible to help the project grow in a healthy manner.
+Although the advantages are numerous, not all software packages require a comprehensive documentation website. However, for any code project that is growing in the number of collaborators, users, and technical complexity, consider coordinating the team to write one as soon as possible to help the project grow in a healthy manner.
 
-### Writing style
+::::::::::::::::::::::::::::::::::::: discussion
 
-Strive to use everyday, jargon-free language. It helps to set an approachable tone that encourages others to use the software and get involved with the project. This will en sure that the code is accesible to the widest possible layers of the research community and foster collaboration.
+When is it appropriate to establish a documentation website?
+Consider the following factors:
 
-Always consider the target audience of your documentation, because your user base may be unaware of some of the unstated assumptions and technical backgroud knowledge that you take for granted.
+- How many resources will it take to write and maintain?
+- How many end-users need the information?
+- Is there a simpler format that can convey the same information?
+
+:::::::::::::::::::::::::::::::::::::
 
 ## Contents
 
@@ -86,6 +105,13 @@ This prevents a situation where potential solutions to common issues do exist, b
 
 An appendix containing frequently asked questions (FAQs) is very useful to save yourself time in responding to common queries from the users of your code.
 
+
+## Writing style
+
+As we discussed in the [episode on READMEs](readmes.md), it's important to strive to use everyday, jargon-free language. It helps to set an approachable tone that encourages others to use the software and get involved with the project. This will en sure that the code is accesible to the widest possible layers of the research community and foster collaboration.
+
+Always consider the target audience of your documentation, because your user base may be unaware of some of the unstated assumptions and technical backgroud knowledge that you take for granted.
+
 ## Tools
 
 There are various tools available to build documentation sites for your research software.
@@ -102,6 +128,8 @@ To create a wiki, which is a simple, easy-to-edit web site, go to the main page
 
 ::: callout
 
+## GitHub Wikis
+
 For more information about the wiki feature on GitHub, see [Documenting your project with wikis](https://docs.github.com/en/communities/documenting-your-project-with-wikis) on the GitHub documentation.
 
 :::