From 229a3c5f3525b94c31054831b6037772e21cace5 Mon Sep 17 00:00:00 2001 From: Liam J Berrisford Date: Fri, 9 May 2025 09:04:19 +0100 Subject: [PATCH 1/4] New course guidance --- _toc.yml | 1 + .../new_course_checklist_timeline.ipynb | 141 ++++++++++++++++++ pyproject.toml | 1 - 3 files changed, 142 insertions(+), 1 deletion(-) create mode 100644 contributing/new_course_checklist_timeline.ipynb diff --git a/_toc.yml b/_toc.yml index 80ffe29c..e3d98870 100644 --- a/_toc.yml +++ b/_toc.yml @@ -300,6 +300,7 @@ parts: - caption: Join Us! chapters: + - file: contributing/new_course_checklist_timeline - file: contributing/contributing - file: contributing/roles - file: contributing/contributing_guidelines diff --git a/contributing/new_course_checklist_timeline.ipynb b/contributing/new_course_checklist_timeline.ipynb new file mode 100644 index 00000000..dea518a8 --- /dev/null +++ b/contributing/new_course_checklist_timeline.ipynb @@ -0,0 +1,141 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "06e8fcaf-9d9a-4584-9747-d7129c96b31c", + "metadata": {}, + "source": [ + "# New Course Checklist and Timeline\n", + "\n", + "## Timescales & Ordering\n", + "\n", + "- **12 weeks before launch** \n", + " - Hold initial logistics call with Programme Management to define learning objectives, course scope, and high-level timeline \n", + " - Confirm roles (Developer, Lead, Helper) and schedule regular check-ins \n", + "\n", + "- **10 weeks before launch** \n", + " - Developer begins drafting core materials (notebooks, slides, datasets, etc.) \n", + " - Create a feature branch on the [CfRR_Courses repo](https://github.com/coding-for-reproducible-research/CfRR_Courses) \n", + "\n", + "- **5 weeks before launch** \n", + " - Submit the first complete draft of materials for internal review \n", + " - Draft metadata in `programme_information` and `section_landing_page` (titles, descriptions, prerequisites) \n", + " - Create the “Where Is My Understanding?” quiz; confirm the quiz `JSON` files render via `JupyterQuiz`\n", + " - Conduct accessibility review (alt text, colour contrast, headings, tables) \n", + "\n", + "- **4 weeks before launch** \n", + " - Integrate content into `JupyterBook`; perform a dry-run build on staging \n", + " - Link all assets (images, data files, interactive widgets) \n", + " - Add course pages to `_toc.yml` \n", + " - If non-Python kernels are used, add them to the non-run list in `_config.yml` \n", + "\n", + "- **1 week before launch** \n", + " - Freeze content; perform final proofreading and complete “top-to-bottom” code execution \n", + " - Hold sign-off meeting with Programme Management \n", + " - Merge the feature branch and add the new course to the live website \n", + "\n", + "- **Post-launch (within 1 week)** \n", + " - Collect initial learner feedback via online form; log any issues as GitHub issues \n", + " - Plan the first update cycle based on participant feedback \n", + "\n", + "## Checklist\n", + "\n", + "### Logistics & Planning\n", + "- [ ] Schedule and hold **initial logistics call** with Programme Management and Delivery Team \n", + "- [ ] Define roles: Developer, Leader, Helper, Participant, Programme Management \n", + "- [ ] Open GitHub Issue for the new course; create feature branch \n", + "\n", + "### Content Creation & Structure\n", + "- [ ] Draft **course objectives** and detailed **learning objectives** for each section of the course\n", + "- [ ] Develop Jupyter notebooks (`.ipynb`) for Python or learnr tutorials (`.Rmd`) for R. Other types of course should be discussed with the central CfRR team\n", + "- [ ] Include slides or PDFs as needed; confirm static content links \n", + "\n", + "### Metadata & Site Integration\n", + "- [ ] Populate `programme_information` \n", + "- [ ] Populate `section_landing_page`\n", + "- [ ] Populate `where_is_my_understanding`\n", + "- [ ] Ensure no overlap or missing sections \n", + "\n", + "### Rendering & Functionality\n", + "- [ ] Build with Jupyter Book on the PR; confirm notebooks render without errors \n", + "- [ ] Test interactive plots, embedded HTML, and widgets \n", + "- [ ] Validate “Where Is My Understanding?” quiz (`display_quiz(\"path/to/quiz.json\")`) \n", + "\n", + "### Asset Linking & URL Encoding\n", + "- [ ] Verify all file paths (spaces, special characters) are realtive paths as used in JupyterBook\n", + "- [ ] Confirm images, data files, and HTML assets load correctly \n", + "\n", + "### Accessibility & Style\n", + "- [ ] Use descriptive headings (H1–H3) and labels \n", + "- [ ] Provide concise alt text for all images \n", + "- [ ] Check colour contrast with a Contrast Checker \n", + "- [ ] Avoid conveying information by colour alone; add text indicators, change shapes of points etc \n", + "- [ ] Use clear, simple language and accessible tables \n", + "\n", + "### Testing & QA\n", + "- [ ] Execute all notebooks end-to-end \n", + "- [ ] Peer-review code comments and markdown explanations \n", + "- [ ] Conduct cross-browser and device checks \n", + "\n", + "\n", + "## Highlighting Issues\n", + "\n", + "Auditing materials refreshes your understanding and helps improve accuracy. Types of issues include: \n", + "- Typographical errors \n", + "- Factual errors \n", + "- Content clarity and comprehension \n", + "- Formatting and layout issues \n", + "- Technical errors (broken links, non-functional elements) \n", + "- Cultural and bias concerns \n", + "- Outdated content \n", + "- Logical fallacies or reasoning errors \n", + "\n", + "## Ensuring Understanding\n", + "- **Multiple-Choice Questions** via JupyterQuiz (`display_quiz(\"path/to/quiz.json\")`) \n", + "- **Coding Exercises** with clear instructions, hints, and dropdown solutions (use Jupyter Book admonitions) \n", + "\n", + "## Language-Specific Standards\n", + "\n", + "### Python\n", + "- Use Jupyter notebooks (`.ipynb`) with well-commented code and markdown \n", + "- Include visualizations, interactive elements, and test notebooks end-to-end \n", + "\n", + "### R\n", + "- Use learnr tutorials (`.Rmd`) distributed via the `cfrr-r-tutorials` repo \n", + "- Define prerequisites, embed interactive exercises/quizzes, and self-contain data and instructions \n", + "\n", + "\n", + " \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "64cc4c3d-6356-4d44-b804-63cffb851b44", + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.9.19" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/pyproject.toml b/pyproject.toml index e3f01163..39a7a174 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -18,7 +18,6 @@ matplotlib = "*" scikit-learn = "*" pyvis = "*" plotly = "^6.0.0" -snowballstemmer = "2.2.0" [build-system] From 017fd4ac91c636e4016d1c9bf8f83922a67d854b Mon Sep 17 00:00:00 2001 From: Liam J Berrisford Date: Fri, 8 Aug 2025 12:45:23 +0100 Subject: [PATCH 2/4] Update based on Fliss comments --- _toc.yml | 2 +- .../new_course_checklist_timeline.ipynb | 107 +++++------------- 2 files changed, 32 insertions(+), 77 deletions(-) diff --git a/_toc.yml b/_toc.yml index 8bad845a..3072c831 100644 --- a/_toc.yml +++ b/_toc.yml @@ -317,11 +317,11 @@ parts: - caption: Join Us! chapters: - file: contributing/community - - file: contributing/new_course_checklist_timeline - file: contributing/contributing - file: contributing/roles - file: contributing/contributing_guidelines - file: contributing/developing_a_course + - file: contributing/new_course_checklist_timeline - file: contributing/suggestions_form - caption: Community Guidelines and Policy Information diff --git a/contributing/new_course_checklist_timeline.ipynb b/contributing/new_course_checklist_timeline.ipynb index dea518a8..1c69b87f 100644 --- a/contributing/new_course_checklist_timeline.ipynb +++ b/contributing/new_course_checklist_timeline.ipynb @@ -9,103 +9,58 @@ "\n", "## Timescales & Ordering\n", "\n", - "- **12 weeks before launch** \n", - " - Hold initial logistics call with Programme Management to define learning objectives, course scope, and high-level timeline \n", - " - Confirm roles (Developer, Lead, Helper) and schedule regular check-ins \n", + "### **12 weeks before delivery** \n", + " - Hold initial logistics call with Programme Management to define learning objectives, course scope, and high-level timeline\n", + " - Confirm roles (Developer, Lead, Helper) and schedule regular check-ins\n", + " - Create a feature branch on the [CfRR_Courses repo](https://github.com/coding-for-reproducible-research/CfRR_Courses), alongside a GitHub Issue \n", + " - Developer begins drafting core materials \n", + "\n", + "#### Checklist Steps \n", + "- [ ] Schedule and hold **initial logistics call** with Programme Management and Delivery Team \n", + "- [ ] Define roles: Developer, Leader, Helper, Participant, Programme Management, and schedule a recurring meeting \n", + "- [ ] Open GitHub Issue for the new course; create feature branch \n", + "- [ ] Draft **course objectives** and detailed **learning objectives** for each section of the course\n", "\n", - "- **10 weeks before launch** \n", - " - Developer begins drafting core materials (notebooks, slides, datasets, etc.) \n", - " - Create a feature branch on the [CfRR_Courses repo](https://github.com/coding-for-reproducible-research/CfRR_Courses) \n", "\n", - "- **5 weeks before launch** \n", - " - Submit the first complete draft of materials for internal review \n", + "### **6 weeks before delivery** \n", + " - Submit the first complete draft of materials for internal review. Liam Berrisford (@liamjberrisford) to validate website functionality (including accessibility features), then a separate reviewer to verify that the course content itself is accurate and appropriate.\n", " - Draft metadata in `programme_information` and `section_landing_page` (titles, descriptions, prerequisites) \n", " - Create the “Where Is My Understanding?” quiz; confirm the quiz `JSON` files render via `JupyterQuiz`\n", - " - Conduct accessibility review (alt text, colour contrast, headings, tables) \n", "\n", - "- **4 weeks before launch** \n", - " - Integrate content into `JupyterBook`; perform a dry-run build on staging \n", - " - Link all assets (images, data files, interactive widgets) \n", - " - Add course pages to `_toc.yml` \n", - " - If non-Python kernels are used, add them to the non-run list in `_config.yml` \n", - "\n", - "- **1 week before launch** \n", - " - Freeze content; perform final proofreading and complete “top-to-bottom” code execution \n", - " - Hold sign-off meeting with Programme Management \n", - " - Merge the feature branch and add the new course to the live website \n", "\n", - "- **Post-launch (within 1 week)** \n", - " - Collect initial learner feedback via online form; log any issues as GitHub issues \n", - " - Plan the first update cycle based on participant feedback \n", - "\n", - "## Checklist\n", - "\n", - "### Logistics & Planning\n", - "- [ ] Schedule and hold **initial logistics call** with Programme Management and Delivery Team \n", - "- [ ] Define roles: Developer, Leader, Helper, Participant, Programme Management \n", - "- [ ] Open GitHub Issue for the new course; create feature branch \n", - "\n", - "### Content Creation & Structure\n", - "- [ ] Draft **course objectives** and detailed **learning objectives** for each section of the course\n", - "- [ ] Develop Jupyter notebooks (`.ipynb`) for Python or learnr tutorials (`.Rmd`) for R. Other types of course should be discussed with the central CfRR team\n", - "- [ ] Include slides or PDFs as needed; confirm static content links \n", - "\n", - "### Metadata & Site Integration\n", + "#### Checklist Steps\n", "- [ ] Populate `programme_information` \n", "- [ ] Populate `section_landing_page`\n", "- [ ] Populate `where_is_my_understanding`\n", - "- [ ] Ensure no overlap or missing sections \n", - "\n", - "### Rendering & Functionality\n", - "- [ ] Build with Jupyter Book on the PR; confirm notebooks render without errors \n", + "- [ ] Add course pages to `_toc.yml` \n", + "- [ ] Ensure no overlap or missing sections \n", "- [ ] Test interactive plots, embedded HTML, and widgets \n", "- [ ] Validate “Where Is My Understanding?” quiz (`display_quiz(\"path/to/quiz.json\")`) \n", - "\n", - "### Asset Linking & URL Encoding\n", "- [ ] Verify all file paths (spaces, special characters) are realtive paths as used in JupyterBook\n", "- [ ] Confirm images, data files, and HTML assets load correctly \n", - "\n", - "### Accessibility & Style\n", - "- [ ] Use descriptive headings (H1–H3) and labels \n", - "- [ ] Provide concise alt text for all images \n", - "- [ ] Check colour contrast with a Contrast Checker \n", - "- [ ] Avoid conveying information by colour alone; add text indicators, change shapes of points etc \n", - "- [ ] Use clear, simple language and accessible tables \n", - "\n", - "### Testing & QA\n", + "- [ ] Include slides or PDFs as needed; confirm static content links \n", "- [ ] Execute all notebooks end-to-end \n", "- [ ] Peer-review code comments and markdown explanations \n", - "- [ ] Conduct cross-browser and device checks \n", - "\n", - "\n", - "## Highlighting Issues\n", "\n", - "Auditing materials refreshes your understanding and helps improve accuracy. Types of issues include: \n", - "- Typographical errors \n", - "- Factual errors \n", - "- Content clarity and comprehension \n", - "- Formatting and layout issues \n", - "- Technical errors (broken links, non-functional elements) \n", - "- Cultural and bias concerns \n", - "- Outdated content \n", - "- Logical fallacies or reasoning errors \n", "\n", - "## Ensuring Understanding\n", - "- **Multiple-Choice Questions** via JupyterQuiz (`display_quiz(\"path/to/quiz.json\")`) \n", - "- **Coding Exercises** with clear instructions, hints, and dropdown solutions (use Jupyter Book admonitions) \n", - "\n", - "## Language-Specific Standards\n", + "### **4 weeks before delivery** \n", + " - Confirm that all feedback and change requests from the internal review have been addressed\n", + " - Link all assets (images, data files, interactive widgets) \n", "\n", - "### Python\n", - "- Use Jupyter notebooks (`.ipynb`) with well-commented code and markdown \n", - "- Include visualizations, interactive elements, and test notebooks end-to-end \n", + "#### Checklist Steps\n", + "- [ ] Confirm there is no outstanding feedback to be actioned from the internal review \n", + "- [ ] Ensure that the Continuous Integration (CI) in the PR for building the Jupyter Book (website) and Accessibility passes\n", "\n", - "### R\n", - "- Use learnr tutorials (`.Rmd`) distributed via the `cfrr-r-tutorials` repo \n", - "- Define prerequisites, embed interactive exercises/quizzes, and self-contain data and instructions \n", "\n", + "### **2 week before delivery** \n", + " - Freeze content; perform final proofreading and complete “top-to-bottom” code execution \n", + " - Please notify Liam Berrisford (@liamjberrisford) that the content is ready for integration into the website and request his final review prior to publication.\n", + " - Merge the feature branch and add the new course to the live website\n", "\n", - " \n" + "#### Checklist Steps\n", + "- [ ] Perform a final proofreading pass; execute a full “top-to-bottom” run of all notebooks \n", + "- [ ] Notify Liam Berrisford (@liamjberrisford) that materials are ready for integration and request his final sign-off \n", + "- [ ] Once approved, merge the feature branch into main and deploy the new course to the live website " ] }, { From ae1d7cc2524191478f878719b808fdeeac9b4c65 Mon Sep 17 00:00:00 2001 From: Liam J Berrisford Date: Tue, 12 Aug 2025 11:48:20 +0100 Subject: [PATCH 3/4] Update new course checklist based on review --- .../new_course_checklist_timeline.ipynb | 76 ++++++++----------- 1 file changed, 32 insertions(+), 44 deletions(-) diff --git a/contributing/new_course_checklist_timeline.ipynb b/contributing/new_course_checklist_timeline.ipynb index 1c69b87f..45405088 100644 --- a/contributing/new_course_checklist_timeline.ipynb +++ b/contributing/new_course_checklist_timeline.ipynb @@ -5,62 +5,50 @@ "id": "06e8fcaf-9d9a-4584-9747-d7129c96b31c", "metadata": {}, "source": [ - "# New Course Checklist and Timeline\n", + "# New Course Checklist and Timeline \n", "\n", - "## Timescales & Ordering\n", + "## Timescales & Ordering \n", "\n", - "### **12 weeks before delivery** \n", - " - Hold initial logistics call with Programme Management to define learning objectives, course scope, and high-level timeline\n", - " - Confirm roles (Developer, Lead, Helper) and schedule regular check-ins\n", - " - Create a feature branch on the [CfRR_Courses repo](https://github.com/coding-for-reproducible-research/CfRR_Courses), alongside a GitHub Issue \n", - " - Developer begins drafting core materials \n", - "\n", - "#### Checklist Steps \n", + "### **12 weeks before delivery** \n", "- [ ] Schedule and hold **initial logistics call** with Programme Management and Delivery Team \n", - "- [ ] Define roles: Developer, Leader, Helper, Participant, Programme Management, and schedule a recurring meeting \n", - "- [ ] Open GitHub Issue for the new course; create feature branch \n", + "- [ ] Identify delivery lead and delivery team members \n", + "- [ ] Identify materials reviewer for **materials appropriateness** review (a subject matter expert who will assess whether the content is accurate, complete, and suitable for the intended audience; this review is separate from the functionality and accessibility review conducted later)\n", + "- [ ] Define roles: Developer, Leader, Helper, Participant, Programme Management \n", + "- [ ] Schedule recurring project check-ins \n", + "- [ ] Open GitHub Issue for the new course; create feature branch in [CfRR_Courses repo](https://github.com/coding-for-reproducible-research/CfRR_Courses) \n", "- [ ] Draft **course objectives** and detailed **learning objectives** for each section of the course\n", - "\n", + "- [ ] Identify a high-level timeline for the delivery of the course \n", "\n", "### **6 weeks before delivery** \n", - " - Submit the first complete draft of materials for internal review. Liam Berrisford (@liamjberrisford) to validate website functionality (including accessibility features), then a separate reviewer to verify that the course content itself is accurate and appropriate.\n", - " - Draft metadata in `programme_information` and `section_landing_page` (titles, descriptions, prerequisites) \n", - " - Create the “Where Is My Understanding?” quiz; confirm the quiz `JSON` files render via `JupyterQuiz`\n", - "\n", - "\n", - "#### Checklist Steps\n", - "- [ ] Populate `programme_information` \n", - "- [ ] Populate `section_landing_page`\n", - "- [ ] Populate `where_is_my_understanding`\n", + "- [ ] Submit first complete draft of materials to the branch \n", + "- [ ] Assign website functionality review to Liam Berrisford (GitHub: @liamjberrisford) \n", + "- [ ] Assign materials appropriateness review to designated reviewer \n", + "- [ ] Populate `programme_information` \n", + "- [ ] Populate `section_landing_page` \n", + "- [ ] Populate `where_is_my_understanding` quiz (`JSON` files confirmed to render via `JupyterQuiz`) \n", "- [ ] Add course pages to `_toc.yml` \n", - "- [ ] Ensure no overlap or missing sections \n", + "- [ ] Check for overlap or missing sections \n", "- [ ] Test interactive plots, embedded HTML, and widgets \n", - "- [ ] Validate “Where Is My Understanding?” quiz (`display_quiz(\"path/to/quiz.json\")`) \n", - "- [ ] Verify all file paths (spaces, special characters) are realtive paths as used in JupyterBook\n", - "- [ ] Confirm images, data files, and HTML assets load correctly \n", - "- [ ] Include slides or PDFs as needed; confirm static content links \n", + "- [ ] Validate quiz rendering (`display_quiz(\"path/to/quiz.json\")`) \n", + "- [ ] Verify all file paths use **relative paths** for Jupyter Book \n", + "- [ ] Confirm all assets (images, data files, HTML) load correctly \n", + "- [ ] Include slides/PDFs as required and confirm static content links \n", "- [ ] Execute all notebooks end-to-end \n", - "- [ ] Peer-review code comments and markdown explanations \n", - "\n", + "- [ ] Peer-review code comments and markdown explanations \n", "\n", "### **4 weeks before delivery** \n", - " - Confirm that all feedback and change requests from the internal review have been addressed\n", - " - Link all assets (images, data files, interactive widgets) \n", - "\n", - "#### Checklist Steps\n", - "- [ ] Confirm there is no outstanding feedback to be actioned from the internal review \n", - "- [ ] Ensure that the Continuous Integration (CI) in the PR for building the Jupyter Book (website) and Accessibility passes\n", - "\n", - "\n", - "### **2 week before delivery** \n", - " - Freeze content; perform final proofreading and complete “top-to-bottom” code execution \n", - " - Please notify Liam Berrisford (@liamjberrisford) that the content is ready for integration into the website and request his final review prior to publication.\n", - " - Merge the feature branch and add the new course to the live website\n", + "- [ ] Address all outstanding feedback from internal reviews \n", + "- [ ] Confirm all assets are correctly linked and functional \n", + "- [ ] Ensure Continuous Integration (CI) build for Jupyter Book passes, including accessibility checks\n", "\n", - "#### Checklist Steps\n", - "- [ ] Perform a final proofreading pass; execute a full “top-to-bottom” run of all notebooks \n", - "- [ ] Notify Liam Berrisford (@liamjberrisford) that materials are ready for integration and request his final sign-off \n", - "- [ ] Once approved, merge the feature branch into main and deploy the new course to the live website " + "### **2 weeks before delivery** \n", + "- [ ] Freeze content \n", + "- [ ] Perform final proofreading and “top-to-bottom” notebook execution \n", + "- [ ] Notify Liam Berrisford (@liamjberrisford) that materials are ready for integration into the website \n", + "- [ ] Obtain final sign-off from Liam \n", + "- [ ] Notify [Jenny McGarvey](https://libguides.exeter.ac.uk/prf.php?id=b1cb0409-e2fc-11ef-b755-0647746d9baf) of the upcoming course; specify that it will be available on the website in approximately 2 weeks. \n", + "- [ ] Merge feature branch into main \n", + "- [ ] Deploy course to live website " ] }, { From 5843711942cbaf82367b87c18a786ae85dbbe070 Mon Sep 17 00:00:00 2001 From: Liam J Berrisford Date: Tue, 12 Aug 2025 11:49:52 +0100 Subject: [PATCH 4/4] Remove need for live website due to github action --- contributing/new_course_checklist_timeline.ipynb | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/contributing/new_course_checklist_timeline.ipynb b/contributing/new_course_checklist_timeline.ipynb index 45405088..e69e4c98 100644 --- a/contributing/new_course_checklist_timeline.ipynb +++ b/contributing/new_course_checklist_timeline.ipynb @@ -47,8 +47,7 @@ "- [ ] Notify Liam Berrisford (@liamjberrisford) that materials are ready for integration into the website \n", "- [ ] Obtain final sign-off from Liam \n", "- [ ] Notify [Jenny McGarvey](https://libguides.exeter.ac.uk/prf.php?id=b1cb0409-e2fc-11ef-b755-0647746d9baf) of the upcoming course; specify that it will be available on the website in approximately 2 weeks. \n", - "- [ ] Merge feature branch into main \n", - "- [ ] Deploy course to live website " + "- [ ] Merge feature branch into main " ] }, {