Merge pull request #51 from FAIR2-for-research-software/50-use-bold-t…

…ext-to-hihglight-key-words

Emphasise key words

config.yaml

@@ -48,8 +48,8 @@ episodes:
 - readmes.md
 - docstrings.md
 - readable.md
-- sites.md
 - contributors.md
+- sites.md
 - cli.md
 
 # Information for Learners

episodes/contributors.md

@@ -49,11 +49,11 @@ Consider these questions amongst the group:
 
 ## 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.
+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.
 
-Potential collaborators should be able to easily find out how to take part and contribute. Developers should be encouraged to use appropriate communication channels to ask questions and inform others of proposed software changes. The contact details for the project administrator or committee should be available and they should be welcome and responsive to any queries.
+Potential collaborators should be able to easily find out how to take part and contribute. Developers should be encouraged to use **appropriate communication channels** to ask questions and inform others of proposed software changes. The contact details for the project administrator or committee should be available and they should be welcome and responsive to any queries.
 
-It’s important to explain how the project is managed so the process for evaluating new features and getting them implemented is clear, such as the code review and approval process. For many projects, a ticket system may be used to raise issues and suggest new features. Software developers often propose new code by creating a branch on the version control system (such as Git) and requesting for those changes to be merged into the main codebase.
+It’s important to explain how the project is managed so the process for evaluating new features and getting them implemented is clear, such as the code review and approval process. For many projects, a **ticket system** may be used to raise issues and suggest new features. Software developers often propose new code by creating a branch on the version control system (such as Git) and requesting for those changes to be merged into the main codebase.
 
 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.
 
@@ -73,12 +73,12 @@ The standard practice for authoring a contribution guide for a software project
 
 The specific contents of this file depend upon the kind of research project, but some useful information to provide typically includes:
 
-- An introduction to the organisation and structure of the code, possibly including diagrams.
-- Instructions to raising issues, suggesting new features, and proposing code changes.
-- Links to additional documentation that's hosted elsewhere, such as a code of conduct or discussion forum.
+- An introduction to the organisation and **structure of the code**, possibly including diagrams.
+- Instructions to **raising issues**, suggesting new features, and proposing code changes.
+- Links to **additional documentation** that's hosted elsewhere, such as a code of conduct or discussion forum.
 - A walkthrough to setting up a development environment, such as guidance on installing developer tools or other prerequisites.
 
-On code hosting platforms such as GitHub, the contribution guide will be created automatically using this `CONTRIBUTING.md` Markdown file.
+On code repository hosting platforms such as [GitHub](https://github.com), the [contribution guide](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors) will be created automatically using this `CONTRIBUTING.md` Markdown file.
 
 :::: challenge
 
@@ -92,11 +92,11 @@ 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!
+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.
+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:
 
@@ -106,9 +106,11 @@ This has the following advantages:
 
 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
+:::: callout
 
-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.
+### Contributor Covenant
+
+Many open-source research software projects adopt the [Contributor Covenant](https://www.contributor-covenant.org/), which is a template charter that may be customised to suit the needs of your collaborators.
 
 ::::
 
@@ -122,15 +124,15 @@ For people who are contributing code to the project, they'll need the following
 
 ### 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.
+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.
+An **architecture diagram** is an efficient way to provide a “map” to help developers to understand and navigate a complex system.
 
 ### 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.
+Many projects follow a set of 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.
+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](https://peps.python.org/pep-0008/) for the Python programming language and the [tidyverse style guide](https://style.tidyverse.org/) in the R statistical language.
 
 ::::::::::::::::::::::::::::::::::::: discussion
 

episodes/introduction.md

@@ -6,7 +6,7 @@ exercises: 2
 
 :::::::::::::::::::::::::::::::::::::: questions
 
-- How do we provide information to users of our research software?
+- 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?
 
@@ -15,7 +15,7 @@ exercises: 2
 ::::::::::::::::::::::::::::::::::::: objectives
 
 - Understand the basic purpose of this course
-- Learn the motivation for learning to document software
+- Learn the **motivation** for learning to document software
 - Be introduced to good software documentation practices
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
@@ -42,11 +42,11 @@ Discuss positive or negative experiences with using research software:
 
 ### 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.
+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.
 
-Research outputs often depend upon the code used to generate them. Clarity and confidence are essential in using code to perform calculations, simulations, or data analysis. All kinds of research processes and analysis pipelines can be made more **reproducible** by providing clear context and instructions for using it.
+Research outputs often **depend upon the code** used to generate them. Clarity and confidence are essential in using code to perform calculations, simulations, or data analysis. All kinds of research processes and analysis pipelines can be made more **reproducible** by providing clear context and instructions for using it.
 
-There are many advantages to making your code more readable. Well-documented software is easier to maintain and has greater sustainability, which means it can continue to be used and modified for a longer period of time, despite changes in technology. If software is more reusable then it encourages others to use it for their research, increasing the number of citations of that software and its overall research impact.
+There are **many advantages** to making your code more readable. Well-documented software is easier to maintain and has greater **sustainability**, which means it can continue to be used and modified for a longer period of time, despite changes in technology. If software is more reusable then it encourages others to use it for their research, increasing the number of citations of that software and its overall research impact.
 
 :::: challenge
 
@@ -58,18 +58,17 @@ Discuss the benefits of writing documentation for your research software.
 
 ::::
 
-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.
+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.
 
-Writing a useful software package that is well-documented and can be reused in the future means that your code could take on a life of its own, with benefits that extend beyond yourself to your collaborators and other researchers in the future. High-quality documentation is a key part of ensuring a healthy software lifecycle. It can make the different between accidentally creating an abandoned piece of "gradware" (a slang term for mysterious code that a former student wrote and nobody else can use) and a successful long-term software project with lasting impact.
+Writing a useful software package that is well-documented and can be reused in the future means that your code could take on a life of its own, with benefits that extend beyond yourself to your collaborators and other researchers in the future. High-quality documentation is a key part of ensuring a healthy **software lifecycle**. It can make the different between accidentally creating an abandoned piece of "gradware" (a slang term for mysterious code that a former student wrote and nobody else can use) and a successful long-term software project with lasting impact.
 
 ## When should I write documentation?
 
-Now! Start writing and sharing documentation for your reseach code from the beginning of your project. It should be a 
-consideration in your _software management plan_, which is a concept discussed in the Module 1a on Software Lifecycle Planning. It's never too late to start documentaing an old code project.
+Now! Start writing and sharing documentation for your reseach code **from the beginning** of your project. It doesn't have to be perfect straight away, but a first draft is more useful than nothing. It should be a consideration in your _software management plan_, which is a concept discussed in the Module 1a on Software Lifecycle Planning. Also, it's never too late to start documentaing an old code 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.
+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.
 
-Keep in touch with other developers and users of the research code and make a note of their feedback. Common questions and problems are a sign that there are issues that must be covered more clearly and in greater depth in the software documentation. Incorporate this feedback into the software documentation using the whichever method is most appropriate, following the guidance in this module.
+**Keep in touch** with other developers and users of the research code and make a note of their feedback. Common questions and problems are a sign that there are issues that must be covered more clearly and in greater depth in the software documentation. **Incorporate this feedback** into the software documentation using the whichever method is most appropriate, following the guidance in this module.
 
 ## Examples
 
@@ -118,7 +117,7 @@ This is a function with a name that doesn't explain what the code will do. There
 
 The logic of the calculation is also... rather cryptic.
 
-Maybe the code works, maybe it doesn't 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
 
@@ -192,7 +191,9 @@ calculate_sine <- function(angle) {
 }
 ```
 
-:::: challenge
+:::
+
+:::: discussion
 
 Read and evaluate this code.
 
@@ -202,11 +203,9 @@ Read and evaluate this code.
 
 ::::
 
-:::
-
 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.
 
-This approach means that our code is much easier to interpret, maintain, and make changes to in the future.
+This approach means that our code is much **easier to interpret**, maintain, and make changes to in the future.
 
 Of course, there may be some syntax in this example that is unfamiliar to you&mdash;but don't worry, we'll learn the basics in this course!
 
@@ -217,14 +216,15 @@ Let's review real-world examples of the documentation for software packages that
 ### NumPy user guide
 
 NumPy is a mathematical package for the Python programming language that's used for linear algebra.
-The [NumPy User Guide](https://numpy.org/doc/2.0/user/index.html#user) is a thorough website that organised into sections that cover the different aspects of using that package.
+The [NumPy User Guide](https://numpy.org/doc/2.0/user/index.html#user) is a **thorough website** that organised into sections that cover the different aspects of using that package.
+
 It includes a beginner's guide, tutorials for different use-cases, and in-depth write-ups of technical details of certain aspects of the code.
 Some of the content is written for a target audience with no assumed knowledge, while other parts are written as a reference for people with some background in mathematics and computer programming.
 
 ### ggplot2 documentation site
 
 ggplot2 is a package for the R statistical language that generates data visualisations and graphics.
-The [ggplot2 documentation](https://ggplot2.tidyverse.org/index.html) has a simple, accessible layout and walks a new user through installing and getting up-and-running with the tool.
+The [ggplot2 documentation](https://ggplot2.tidyverse.org/index.html) has a simple, accessible layout and **walks a new user through** installing and getting up-and-running with the tool.
 The page provides a "cheat sheet" which is a reference guide that lists commonly-used commands in an attractice two-page layout.
 The documentation site is moderate in scope and links to several external resources, such as online courses hosted elsewhere.