Developing a Course Guidance#
If you are interested in developing and contributing some course content or a complete course to the CfRR program, then please ensure you first read the Contributing Guide.
The goal of this page is to provide some helpful hints on how to develop a course for the CfRR programme. While the courses are on a diverse range of topics, there is a desire for all of the courses that are offered to have some degree of similarity in approach and quality. Below are some of the key points that have been raised. The CfRR program is always looking to improve, and if you feel there is anything that should be added to this page, please open a GitHub issue to start a discussion.
Tools#
For making content for CfRR, we recommend making use of JupyterLab, the next-generation user interface for Project Jupyter, offering an extensible environment for interactive computing and data science workflows. JupyterLab is a modular and customisable architecture; JupyterLab provides a powerful platform for working with Jupyter Notebooks, text editors, terminals, and other interactive components in a unified interface.
Defining Your Goals#
Before you start creating your course content, it is vital to outline the learning objectives. One way to think about the learning objectives is at different levels. For example, an overall course objective for the objectives of an Introduction to Python course could be:
Understand and declare the basic data types in Python. In the particular part of the course where you deliver content on data types in Python, you would then include the following more granular learning objectives:
Know the different data types within Python
Create and use new variables in Python
Assign values to variables and change these values later
Perform some simple operations on variables
Your course objectives should be longer-term strategic goals, with the learning objectives being smaller goals that are individually addressed shortly after being presented.
Creating Accessible Content#
Ensuring that your content is accessible to all users, including those with disabilities, is a key aspect of creating inclusive educational resources. Below are some guidelines and best practices to help you make your course materials accessible:
1. Use Descriptive Headings and Labels#
Headings: Organize your content with proper headings (H1, H2, H3) to ensure a logical structure and easier navigation for screen readers.
Labels: Use clear, descriptive labels for buttons, links, and forms. Avoid vague labels like “click here” or “read more”, without explicit content describing what the link refers to.
2. Provide Alt Text for Images#
Every image should have an
altattribute that describes the content and function of the image. Keep descriptions concise yet informative, especially for complex images like charts and diagrams.
3. Ensure Sufficient Color Contrast#
Use high-contrast color schemes for text and background to make the content readable for users with visual impairments. Tools like the WebAIM Contrast Checker can help you ensure compliance with accessibility standards.
4. Avoid Relying on Color Alone#
Don’t use color as the sole way to convey important information. For example, if you’re using color to indicate correct answers, add additional text-based indicators are helpful, such as “Answer Correct” or “Answer Incorrect”.
5. Write Clear and Simple Text#
Write in plain language whenever possible. Avoid complex jargon unless it’s absolutely necessary, and provide explanations for technical terms when used.
6. Use Accessible Tables#
When creating tables, include clear headers and captions. Ensure that tables are not used purely for layout purposes, but only for presenting data.
Accessible Web Content Further Reading#
The following resouces provide additional material on creating accessible content for the web:
Accessible Education Practices Further Reading#
For those looking to explore accessible educational practices further, the following resources are helpful:
Ensuring Understanding#
As part of the course, you should aim to ensure that you have some content that a student can use to assess whether they have understood the concept being discussed and outlined in the learning objectives. Two primary methods of doing this are coding exercises and multiple-choice questions.
Creating Multiple Choice Questions in CfRR#
Within CfRR, multiple-choice questions are implemented using JupyterQuiz. JupyterQuiz is a Python package that enables the creation of interactive quizzes within Jupyter Notebooks. The package provides a convenient way to design and implement quizzes for educational purposes, assessments, or interactive learning experiences.
The following code can be used to render an interactive quiz. It will import the needed Python package and then render the quiz content.
from jupyterquiz import display_quiz
display_quiz("filepath/to/quiz.json")
You can define the actual quiz questions within a JSON file, with an example file given below, where the correct answer is C. The question itself can be changed within the relevant field.
[
{
"question": "Is this a question?",
"type": "many_choice",
"answers": [
{
"answer": "Answer A",
"correct": false,
"feedback": "Really Incorrect."
},
{
"answer": "Answer B",
"correct": false,
"feedback": "Incorrect."
},
{
"answer": "Answer C",
"correct": true,
"feedback": "Correct."
},
{
"answer": "Answer D",
"correct": false,
"feedback": "Relatively Incorrect."
}
]
}
]
A file can contain as many questions as desired, with the top level {} giving individual questions that can be chained together in sequence with the use of a comma to separate them as below.
[
{
"question": "Is this a question?",
"type": "many_choice",
"answers": [
{
"answer": "Answer A",
"correct": false,
"feedback": "Really Incorrect."
},
{
"answer": "Answer B",
"correct": false,
"feedback": "Incorrect."
},
{
"answer": "Answer C",
"correct": true,
"feedback": "Correct."
},
{
"answer": "Answer D",
"correct": false,
"feedback": "Relatively Incorrect."
}
]
},
{
"question": "Is this a question aswell?",
"type": "many_choice",
"answers": [
{
"answer": "Answer A",
"correct": false,
"feedback": "Really Incorrect."
},
{
"answer": "Answer B",
"correct": false,
"feedback": "Incorrect."
},
{
"answer": "Answer C",
"correct": true,
"feedback": "Correct."
},
{
"answer": "Answer D",
"correct": false,
"feedback": "Relatively Incorrect."
}
]
}
]
The quiz that is outlined above would then be rendered within the actual website as:
from jupyterquiz import display_quiz
display_quiz("questions/example_questions.json")
Within the actual website, you likely don’t want the code that renders the quiz to be visible. To remove the code block with the Python code within, the tag “hide-input” can be given to the code block. If you are using JupyterLab, then it is easy to add a cell tag by clicking the cog icon in the top right of the user interface and then clicking to add “Cell Tags” while the cell that you want to hide is being edited. A range of other cell tags can also be added, as described here: Interactive Widgets. The webpage on the Jupyter Book documentation website guides using interactive elements such as hiding and showing content within Jupyter Book pages. It demonstrates how to use Jupyter widgets to create interactive components that enhance users’ reading and learning experiences.
Creating Coding Exercises#
Including coding exercises helps ensure that course participants understand the content discussed. The CfRR Jupyter book website is built and attached to the notebooks themselves, so it can write and run code within the website, providing a seamless and uniform experience across the coding exercises included in your course content.
When developing a coding exercise, it is always good to offer detailed and step-by-step instructions to guide the reader through the exercise. It is also the case that you may wish to have different levels of instruction that can then be revealed to students if they need further help. It is also possible to have some content hidden behind a clickable button, as shown below, which is achieved with straightforward markdown content as described here: Components of Jupyter Book. Below is the markdown content for an example coding exercise using the markdown style of the Jupyter book, and what it would look like when rendered.
The following markdown content would then render the following coding exercise seen immediately below:
#### Exercise: Calculate the Sum of a List of Numbers
##### Objective
Write a Python function that takes a list of numbers as input and returns the sum of those numbers. This exercise will help ensure you understand basic list operations and functions in Python.
##### Instructions
- Define a function named calculate_sum that takes one argument, numbers_list, which is a list of numbers.
- Initialize a variable total to 0.
- Use a for loop to iterate through each number in numbers_list.
- Add each number to the total variable.
- Return the total variable.
```{admonition} Click here for hints!
:class: tip, dropdown
- Start by defining the function with the appropriate name and parameter.
- Use a for loop to iterate over the elements of the list.
- Remember to initialize the sum variable before the loop.
- Add each element to the sum variable within the loop.
- Return the sum variable at the end of the function.
```
```{admonition} Exercise Solution
:class: dropdown
```python
def calculate_sum(numbers_list):
total = 0
for number in numbers_list:
total += number
return total
# Test the function
print(calculate_sum([1, 2, 3, 4, 5])) # Expected output: 15
```
```
Exercise: Calculate the Sum of a List of Numbers#
Objective#
Write a Python function that takes a list of numbers as input and returns the sum of those numbers. This exercise will help ensure you understand basic list operations and functions in Python.
Instructions#
Define a function named calculate_sum that takes one argument, numbers_list, which is a list of numbers.
Initialize a variable total to 0.
Use a for loop to iterate through each number in numbers_list.
Add each number to the total variable.
Return the total variable.
Click here for hints!
Start by defining the function with the appropriate name and parameter.
Use a for loop to iterate over the elements of the list.
Remember to initialize the sum variable before the loop.
Add each element to the sum variable within the loop.
Return the sum variable at the end of the function.
Exercise Solution
def calculate_sum(numbers_list):
total = 0
for number in numbers_list:
total += number
return total
# Test the function
print(calculate_sum([1, 2, 3, 4, 5])) # Expected output: 15
Summary#
The overview on this page is only meant to give a brief overview of some of the possible course elements you develop. A range of other elements, such as multimedia, could be included that have yet to be explored here. Please feel free to include additional elements as they relate to the course that you are working on, and feel free to write some additional guidance that can be incorporated into this page, as well as develop best practices!