Merge branch 'main' of https://github.com/Joe-Heffer-Shef/FAIR4RS-Doc…

…umentation

FAIR4RS-Documentation.Rproj

@@ -1,7 +1,7 @@
 Version: 1.0
 
-RestoreWorkspace: No
-SaveWorkspace: No
+RestoreWorkspace: Default
+SaveWorkspace: Default
 AlwaysSaveHistory: Default
 
 EnableCodeIndexing: Yes
@@ -14,6 +14,5 @@ LaTeX: pdfLaTeX
 
 AutoAppendNewline: Yes
 StripTrailingWhitespace: Yes
-LineEndingConversion: Posix
 
 BuildType: Website

episodes/contributors.md

@@ -60,13 +60,45 @@ Create a new file called `CONTRIBUTING.md` and populate it with a few sentences.
 
 ::::
 
+## Software project governance
+
+Project governance defines the scope and aims of a research software engineering project, and determines how decisions will be made and carried out. It sets out the processes and responsibilities that collaborators must understand to take part. This is something that should be considered when preparing a software management plan, as discussed in Module 1a of this course. This is important to make sure that questions of who does what, and how, are stated clearly so that everyone can understand and collaborate effectively to produce excellent research software. It's worthwhile to think about this early on in a project to avoid potential pitfalls later on!
+
+### Code of conduct
+
+A code of conduct provides guidelines for the expected behaviour of people who are involved in the project. You may want to provide some general tips to create a productive community of researchers around the software, such as creating positive interactions between contributors, treat others with respect and dignity, and recommendations for processes for handling differences of opinion.
+
+This has the following advantages:
+
+- Fosters a healthy, **collaborative working environment** where people feel respected, included, and can freely share ideas.
+- **Managing expectations** and creating clear rules will reduce the amount of time wasted due to misunderstanding and conflicts.
+- **Build a communinity**: an ethically-run and transparent project will encourage contributors to share the values of the project and remain engaged.
+
+For many working in a research context, there are additional considerations to ensure that institutional policies, ethics, and data protection regulations are carefully observed. These protocols are outside the scope of this document, but these factors should be clearly communicated to all contributors.
+
+:::: tip
+
+Many open-source research software projects adopt the [Contributor Covenant](https://www.contributor-covenant.org/), which can also be customised to suit the needs of your collaborators.
+
+::::
+
 ## Developer notes
 
+For people who are contributing code to the project, they'll need the following information:
+
+- Which version control system is being used. Typically, this will be `git` or similar tools, as discussed in Module 2 of this course.
+- How to add automatic tests and whether a testing framework is in place.
+- Describe the code organisation and package structure.
+
+### Technical documentation
+
 System documentation is important for new contributors to familiarise themselves with the codebase and as a reference for existing engineers. There should be a concise description of how the system works from a more technical perspective, with the intended audience being software developers, rather than the research users.
 
 An architecture diagram is an efficient way to provide a “map” to help developers to understand and navigate a complex system.
 
-A coding style guide will help to ensure consistency across all the code written as part of a collaborative project, which helps others to read and interpret the code, making it easier to maintain in the long run. The code style rules should cover things like the way to describe functions, how to indent code, and naming conventions for variables.
+### Coding conventions
+
+Many projects following programming standards to manage code quality. A coding style guide will help to ensure consistency across all the code written as part of a collaborative project, which helps others to read and interpret the code, making it easier to maintain in the long run. The code style rules should cover things like the way to describe functions, how to indent code, and naming conventions for variables.
 
 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.
 
@@ -85,3 +117,4 @@ To find out more about creating healthy communities of developers to collaborate
 
 - GitHub Docs [Setting guidelines for repository contributors](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors)
 - H. Gruson and H. Turner Software Sustainability Institute [Opening the door to new contributors in open source projects](https://www.software.ac.uk/blog/opening-door-new-contributors-open-source-projects)
+- Stephan Druskat [And then there were users: Designing governance for open research software projects](https://www.youtube.com/watch?v=_RMYO_20L-U) Talk at RSECon23 in Swansea.

episodes/docstrings.md

@@ -6,31 +6,36 @@ exercises: 2
 
 :::::::::::::::::::::::::::::::::::::: questions 
 
-- What is a **documentation string**?
+- How do we **describe our code**?
+- What are **documentation strings**?
 - Why are documentation strings useful for **research software**?
-- **How** do we write documentation strings?
+- **How do we write** documentation strings?
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
 ::::::::::::::::::::::::::::::::::::: objectives
 
 - Understand the **purpose** of documentation strings
 - Learn **how to write** documentation strings that will be useful for other researchers
-- Introduce ways to describe the parameters and return values of functions
+- Introduce ways to describe the **parameters** and return values of functions
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
-## Introduction
+## How do we describe our code?
 
-If you’re publishing a research software package, one of the most common ways that its users will learn to interact with the code is by reading the documentation for each individual function.
+If you’re publishing a research software package, one of the most common ways that its users will learn to interact with the code is by reading the documentation **for each individual function**.
 
-We learned about functions in an earlier module. Functions help us to break our code into smaller units that have a single purpose. By documenting those functions effectively, we aim to explain that purpose to future users and maintainers of that code. We also need to describe all the expected inputs and outputs of the function.
+We learned about _functions_ in an earlier module. Functions help us to break our code into smaller units that have a single purpose. By documenting those functions effectively, we aim to **explain their purpose** to future users and maintainers of that code. We also need to describe all the expected inputs and outputs of the function.
 
 We describe functions by using a feature of many programming languages called documentation strings, usually abbreviated to **docstring**. A documentation string is a piece of text that describes that piece of code and helps people to use it.
 
-To make a docstring, we put a string as the first line of a function (or other object.) For example, for a simple Python function that calculates the sum of two numbers:
+To make a docstring, we write special comments in our code using syntax which is specific to each programming language, although the principle is the same.
 
-TODO R examples
+::: group-tab 
+
+### Python
+
+In Python, we put a string as the first line of a function (or other object.) For example, for a simple Python function that calculates the sum of two numbers:
 
 ```python
 def add(x, y):
@@ -40,13 +45,67 @@ def add(x, y):
     return x + y
 ```
 
+### R
+
+In R, we use a comment with a single quote `#'` to specify a documentation string for a function.
+
+```R
+#' Calculate the sum of two numbers.
+add <- function(x, y) {
+  return(x + y)
+}
+```
+
+:::
+
+Whenever you add functionality to a code project, consider wrapping it up into a function.
+It may help to **write the docstring first** to help work through what the purpose of your new code is before you start!
+
 ::::::::::::::::::::::::::::::::: challenge
 
 Write a documentation string for a function.
+Create a script called `oddsong` and define a function named `identify()` that'll be used to identify bird songs by inspecting an audio file to provide the name of that species.
 
 ::::::::::::::::: solution
 
-TODO
+::: group-tab
+
+### Python
+
+1. Create a new Python script by creating a file called `oddsong.py`;
+2. Open the file for editing;
+3. Create a new function called `identify()`;
+4. Write a string that describes the code.
+
+```python
+def identify(audio_file):
+    """
+    Identify a bird based on the sound of its call.
+    """
+
+    print("Identifying bird vocalisation...")
+
+    return "Hirundo atrocaerulea"
+```
+
+### R
+
+1. Create a new R script by creating a file called `oddsong.R`;
+2. Open the file for editing;
+3. Create a new function called `identify()`;
+4. Write a string that describes the code.
+
+```R
+#' Identify a bird based on the sound of its call.
+identify <- function(audio_file) {
+
+    print("Identifying bird vocalisation...")
+
+    return("Hirundo atrocaerulea")
+}
+```
+
+:::
 
 ::::::::::::::::::::::::::
 

episodes/readable.md

@@ -79,8 +79,8 @@ def count_word_occurrences(filename, word_to_count):
 
 Without syntax highlighting:
 
-```output
-# Function to count word occurrences in a text file
+```default
+#' Function to count word occurrences in a text file
 count_word_occurrences <- function(filename, word_to_count) {
   text_file <- file(filename, "r")
   word_count <- 0

episodes/readmes.md

@@ -6,6 +6,7 @@ exercises: 2
 
 :::::::::::::::::::::::::::::::::::::: questions 
 
+- How do we **introduce** our software to new researchers and developers?
 - What is a README file?
 - How do I write a README for my research code?
 - What are the contents of a good README file?

learners/reference.md

@@ -57,4 +57,4 @@ Documentation site
 ## Further resources
 
 - Write the Docs, [A beginner’s guide to writing documentation](https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/)
-- S. Druskat and S. Harriet, *Software Sustainability Institute* [What are best practices for research software] documentation?(https://www.software.ac.uk/blog/what-are-best-practices-research-software-documentation)
+- S. Druskat and S. Harriet, *Software Sustainability Institute* [What are best practices for research software documentation?](https://www.software.ac.uk/blog/what-are-best-practices-research-software-documentation)