Skip to content

Commit

Permalink
Link fixing (#942)
Browse files Browse the repository at this point in the history
Fixing broken or incorrect links in some modules and documentation. 

---------

Co-authored-by: Meredith Lee <69471812+leemc-data-ed@users.noreply.github.com>
  • Loading branch information
franzenr and leemc-data-ed authored Aug 8, 2024
1 parent befb96d commit 032a62c
Show file tree
Hide file tree
Showing 25 changed files with 73 additions and 73 deletions.
6 changes: 3 additions & 3 deletions .github/ISSUE_TEMPLATE/qa-for-exercise-modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ assignees: ''
----
Date: {yyyy-mm-dd}
Reviewer: {your name}
qa_template_version: 2.0.1
qa_template_version: 2.0.2
Name of Module: {take from the title of the main markdown in the PR}
Current Liascript URL: {makes it easy for reviewers and authors to look at content as learners will}

Expand All @@ -25,7 +25,7 @@ Current Liascript URL: {makes it easy for reviewers and authors to look at conte
## Module Organization
* [ ] Front matter is at the very top of the file
* [ ] Check included front matter fields against the [front matter checklist](https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/main/docs.md#your-front-matter-checklist) to make sure all necessary fields are included. In addition, check the following details:
* [ ] module version number of at least 1.0.0 if first public version or if this is an update then an [appropriately incremented version number](versioning_guidelines.md)
* [ ] module version number of at least 1.0.0 if first public version or if this is an update then an [appropriately incremented version number](https://github.com/arcus/education_modules/blob/main/versioning_guidelines.md)
* [ ] current_version_description is a short, present-tense text fragment without bullets, and gives a learner-centric quick overview of version changes from the learner perspective
* [ ] module_type should be `exercise`
* [ ] estimated_time_in_minutes should be a number 0-60
Expand All @@ -52,7 +52,7 @@ Current Liascript URL: {makes it easy for reviewers and authors to look at conte
* [ ] Unusual words, or words taking on a very specific meaning in context, are always defined for the learner, either on the page (e.g. using footnotes) or with links to a definition/glossary.
* [ ] Provides pronunciation guides for any especially unusual words of particular importance (a common example is package names, such as dplyr)
* [ ] Avoids unnecessarily gendered language (e.g. uses "they" singular rather than "he or she" for an unknown person).
* [ ] Informative link text (e.g. instead of "To learn more about python, click [here](www.example.com)", say "Read this article to [learn more about python](www.example.com).")
* [ ] Informative link text (e.g. instead of "To learn more about python, click [here](https://www.example.com)", say "Read this article to [learn more about python](https://www.example.com).")
* [ ] Uses specially formatted highlight boxes consistently and appropriately
* [ ] Short, digestible pieces --- avoids long paragraphs and breaks long sections up with sub-headers
* [ ] All links work (See [Branch References to Change prior to PR Approval](#Branch-References-to-Change-prior-to-PR-Approval) for a place to keep track of internal references that will need to be updated.)
Expand Down
8 changes: 4 additions & 4 deletions .github/ISSUE_TEMPLATE/qa-for-standard-modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ assignees: ''
----
Date: {yyyy-mm-dd}
Reviewer: {your name}
qa_template_version: 2.0.1
qa_template_version: 2.0.2
Name of Module: {take from the title of the main markdown in the PR}
Current Liascript URL: {makes it easy for reviewers and authors to look at content as learners will}

Expand All @@ -25,7 +25,7 @@ Current Liascript URL: {makes it easy for reviewers and authors to look at conte
## Module Organization
* [ ] Front matter is at the very top of the file
* [ ] Check included front matter fields against the [front matter checklist](https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/main/docs.md#your-front-matter-checklist) to make sure all necessary fields are included. In addition, check the following details:
* [ ] module version number of at least 1.0.0 if first public version or if this is an update then an [appropriately incremented version number](versioning_guidelines.md)
* [ ] module version number of at least 1.0.0 if first public version or if this is an update then an [appropriately incremented version number](https://github.com/arcus/education_modules/blob/main/versioning_guidelines.md)
* [ ] current_version_description is a short, present-tense text fragment without bullets, and gives a learner-centric quick overview of version changes from the learner perspective
* [ ] module_type should be `standard`
* [ ] estimated_time_in_minutes should be a number 0-60
Expand All @@ -52,7 +52,7 @@ Current Liascript URL: {makes it easy for reviewers and authors to look at conte
* [ ] Unusual words, or words taking on a very specific meaning in context, are always defined for the learner, either on the page (e.g. using footnotes) or with links to a definition/glossary.
* [ ] Provides pronunciation guides for any especially unusual words of particular importance (a common example is package names, such as dplyr)
* [ ] Avoids unnecessarily gendered language (e.g. uses "they" singular rather than "he or she" for an unknown person).
* [ ] Informative link text (e.g. instead of "To learn more about python, click [here](www.example.com)", say "Read this article to [learn more about python](www.example.com).")
* [ ] Informative link text (e.g. instead of "To learn more about python, click [here](https://www.example.com)", say "Read this article to [learn more about python](https://www.example.com).")
* [ ] Uses specially formatted highlight boxes consistently and appropriately
* [ ] Short, digestible pieces --- avoids long paragraphs and breaks long sections up with sub-headers
* [ ] All links work (See [Branch References to Change prior to PR Approval](#Branch-References-to-Change-prior-to-PR-Approval) for a place to keep track of internal references that will need to be updated.)
Expand Down Expand Up @@ -104,4 +104,4 @@ List here any internal references (stated or hyperlinked) that work now because

## Just Before Approval

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.
Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.
8 changes: 4 additions & 4 deletions .github/ISSUE_TEMPLATE/qa-for-wrapper-modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ assignees: ''
----
Date: {yyyy-mm-dd}
Reviewer: {your name}
qa_template_version: 2.0.1
qa_template_version: 2.0.2
Name of Module: {take from the title of the main markdown in the PR}
Current Liascript URL: {makes it easy for reviewers and authors to look at content as learners will}

Expand All @@ -25,7 +25,7 @@ Current Liascript URL: {makes it easy for reviewers and authors to look at conte
## Module Organization
* [ ] Front matter is at the very top of the file
* [ ] Check included front matter fields against the [front matter checklist](https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/main/docs.md#your-front-matter-checklist) to make sure all necessary fields are included. In addition, check the following details:
* [ ] module version number of at least 1.0.0 if first public version or if this is an update then an [appropriately incremented version number](versioning_guidelines.md)
* [ ] module version number of at least 1.0.0 if first public version or if this is an update then an [appropriately incremented version number](https://github.com/arcus/education_modules/blob/main/versioning_guidelines.md)
* [ ] current_version_description is a short, present-tense text fragment without bullets, and gives a learner-centric quick overview of version changes from the learner perspective
* [ ] module_type should be `wrapper`
* [ ] estimated_time_in_minutes should be a number 0-60
Expand All @@ -52,7 +52,7 @@ Current Liascript URL: {makes it easy for reviewers and authors to look at conte
* [ ] Unusual words, or words taking on a very specific meaning in context, are always defined for the learner, either on the page (e.g. using footnotes) or with links to a definition/glossary.
* [ ] Provides pronunciation guides for any especially unusual words of particular importance (a common example is package names, such as dplyr)
* [ ] Avoids unnecessarily gendered language (e.g. uses "they" singular rather than "he or she" for an unknown person).
* [ ] Informative link text (e.g. instead of "To learn more about python, click [here](www.example.com)", say "Read this article to [learn more about python](www.example.com).")
* [ ] Informative link text (e.g. instead of "To learn more about python, click [here](https://www.example.com)", say "Read this article to [learn more about python](https://www.example.com).")
* [ ] Uses specially formatted highlight boxes consistently and appropriately
* [ ] Short, digestible pieces --- avoids long paragraphs and breaks long sections up with sub-headers
* [ ] All links work (See [Branch References to Change prior to PR Approval](#Branch-References-to-Change-prior-to-PR-Approval) for a place to keep track of internal references that will need to be updated.)
Expand Down Expand Up @@ -104,4 +104,4 @@ List here any internal references (stated or hyperlinked) that work now because

## Just Before Approval

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.
Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.
4 changes: 2 additions & 2 deletions _for_authors/inclusivity_guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This is a working document articulating our goals and standards for creating content that will be valuable and accessible to as wide a range of users as possible. Specifically, we are designing with a variety of ["edge" users](https://guide.inclusivedesign.ca/activities/inclusive-design-mapping/) in mind: those with limited access to visual content or auditory content, those with barriers related to attention, cognition, sensory processing, or language, and those with limited technology access and/or financial resources. A core principle is to allow users as much flexibility as possible to configure their learning experiences to meet their own needs and preferences.

The guidelines presented here are inspired by several other guides including the [Web Content Accessibility Guidelines WCAG21](https://www.w3.org/WAI/WCAG21/quickref) and [The Inclusive Learning Design Handbook](https://handbook.floeproject.org/approachesoverview). Recommendations specific to educational videos can be found [here](https://ctl.wiley.com/how-to-ensure-accessibility-for-educational-videos/).
The guidelines presented here are inspired by several other guides including the [Web Content Accessibility Guidelines WCAG21](https://www.w3.org/WAI/WCAG21/quickref) and [The Inclusive Learning Design Handbook](https://handbook.floeproject.org/approaches/). Recommendations specific to educational videos can be found [here](https://ctl.wiley.com/how-to-ensure-accessibility-for-educational-videos/).

## Guidelines

Expand All @@ -22,7 +22,7 @@ The guidelines presented here are inspired by several other guides including the
- Color should never be the sole method for distinguishing visual content
* Provide clear, consistent organization and content structure to reduce cognitive load for users
- Use clear, informative headers for each subsection. The resulting table of contents should give a good sense of the flow and structure of the module. Avoid titles and headers that sacrifice clarity for playfulness.
- Use informative link text (e.g. instead of "To learn more about python, click [here](www.example.com)", say "Read this article to [learn more about python](www.example.com).")
- Use informative link text (e.g. instead of "To learn more about python, click [here](https://www.example.com)", say "Read this article to [learn more about python](https://www.example.com).")
- Use parallel structure across modules covering similar content.
- Use consistent formatting (e.g. consistent page headers and footers, consistent style controlled by css file)
* Reduce language barriers
Expand Down
14 changes: 7 additions & 7 deletions _for_authors/write_a_module.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,15 +43,15 @@ In our use of the FAIR principles we prioritize whenever possible the use of and

### Licensing

As part of our FAIR methodology, we give our materials away free of charge and free of limits on their use, as long as proper citation is given. We do this via our use of the [Creative Commons Attribution-ShareAlike 4.0 International license](LICENSE). You may not include proprietary data or intellectual property in a module you submit for inclusion in this project, nor may you limit your module's use to only your institution or promote commercial tools or resources that you have financial interest in. By submitting materials for inclusion among these modules, you agree to donate your materials free of charge and agree to their use in accordance with our license.
As part of our FAIR methodology, we give our materials away free of charge and free of limits on their use, as long as proper citation is given. We do this via our use of the [Creative Commons Attribution-ShareAlike 4.0 International license](https://github.com/arcus/education_modules/blob/main/LICENSE). You may not include proprietary data or intellectual property in a module you submit for inclusion in this project, nor may you limit your module's use to only your institution or promote commercial tools or resources that you have financial interest in. By submitting materials for inclusion among these modules, you agree to donate your materials free of charge and agree to their use in accordance with our license.

### Transparency

We believe that greater transparency leads to better science, and we aim to not only promote transparency to our learners, but apply the same transparency demands to our own work. We make problem reports ([GitHub "issues"](https://github.com/arcus/education_modules/issues)) and their resolutions public, and we intend to share any evidence of the effectiveness (or ineffectiveness) of our modules as soon as practicable.

### Inclusive Design

We expect authors to design with a variety of ["edge" users](https://guide.inclusivedesign.ca/activities/inclusive-design-mapping/) in mind: those with limited access to visual content or auditory content, those with barriers related to attention, cognition, sensory processing, or language, and those with limited technology access and/or financial resources. Wherever possible we encourage a multi-modal approach to education, such that no instruction relies solely on a single type of communication (text, video, audio, images, code) but provides several ways to engage with materials. Please review our [inclusivity guidelines](inclusivity_guidelines.md). We encourage you to avoid the mistake of writing a module and then attempting to remediate any accessibility issues after the module is written. It is generally much more effective for module authors and for all learners if a widely inclusive design is considered at the outset, with pedagogical decisions always keeping a variety of learners in mind.
We expect authors to design with a variety of ["edge" users](https://guide.inclusivedesign.ca/activities/inclusive-design-mapping/) in mind: those with limited access to visual content or auditory content, those with barriers related to attention, cognition, sensory processing, or language, and those with limited technology access and/or financial resources. Wherever possible we encourage a multi-modal approach to education, such that no instruction relies solely on a single type of communication (text, video, audio, images, code) but provides several ways to engage with materials. Please review our [inclusivity guidelines](https://github.com/arcus/education_modules/blob/main/_for_authors/inclusivity_guidelines.md). We encourage you to avoid the mistake of writing a module and then attempting to remediate any accessibility issues after the module is written. It is generally much more effective for module authors and for all learners if a widely inclusive design is considered at the outset, with pedagogical decisions always keeping a variety of learners in mind.

## Use GitHub

Expand Down Expand Up @@ -83,19 +83,19 @@ A module in this project will be brief (one hour or less) and therefore of limit

Begin your file structure by creating a folder with an expressive name, using lower case and underscores, like `lasso_and_ridge_ml_in_r` or `bayesian_stats_in_python`. This will hold all of the files that are unique to your module.

To start writing the main file that will make up your module, use one of our [templates](_module_templates). We have three templates:
To start writing the main file that will make up your module, use one of our [templates](https://github.com/arcus/education_modules/blob/main/_module_templates). We have three templates:

* Our [standard template](../_module_templates/template_standard.md) is for modules that teach a skill using mostly original material.
* Our [wrapper template](../_module_templates/template_wrapper.md) is for modules that teach a skill using mostly existing material that we point learners to. For example, a module teaching learners how to install RStudio will likely depend on Posit materials.
* Our [exercise template](../_module_templates/template_exercise.md) is for modules that do not teach additional skills but offer a practical exercise / sample project.
* Our [standard template](https://github.com/arcus/education_modules/blob/main/_module_templates/template_standard.md) is for modules that teach a skill using mostly original material.
* Our [wrapper template](https://github.com/arcus/education_modules/blob/main/_module_templates/template_wrapper.md) is for modules that teach a skill using mostly existing material that we point learners to. For example, a module teaching learners how to install RStudio will likely depend on Posit materials.
* Our [exercise template](https://github.com/arcus/education_modules/blob/main/_module_templates/template_exercise.md) is for modules that do not teach additional skills but offer a practical exercise / sample project.

Make a copy of the appropriate template and save it within your new folder with an almost identical title to the folder, one that ends in `.md`, like `lasso_and_ridge_ml_in_r.md` or `bayesian_stats_in_python.md`.

Technical instructions for how to write a module in LiaScript are available in the [DART module docs](https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/main/docs.md#1). The docs includes some boilerplate text to show you how to write in LiaScript flavored markdown (it's pretty similar to other markdown flavors, but with a few things added in), including lots of examples you can copy and paste. It also includes information about important elements needed to meet our requirements for a module, such as including formative assessments.

Importantly, consider starting to write your module by beginning with the description and learning objectives. This will help you scope your topic. Three to five learning objectives are plenty for a module of about one hour's duration.

We know that this is a complex process, and you may have questions about how to use our [templates](../_module_templates/) or have other questions about any part of this process. Please don't hesitate to reach out to ask questions or let us know if we haven't explained something fully. This is how we improve! If you send us an email at [dart@chop.edu](mailto:dart@chop.edu), we'll try to respond. If we realize we need to improve the documentation, we may use your paraphrased email (stripped of all identifying information) to create an [issue](../issues) so that everyone using the repository knows we're working on a fix. In fact, if you feel comfortable, you, too, can [create an issue](/../issues/new)!
We know that this is a complex process, and you may have questions about how to use our [templates](https://github.com/arcus/education_modules/blob/main/_module_templates) or have other questions about any part of this process. Please don't hesitate to reach out to ask questions or let us know if we haven't explained something fully. This is how we improve! If you send us an email at [dart@chop.edu](mailto:dart@chop.edu), we'll try to respond. If we realize we need to improve the documentation, we may use your paraphrased email (stripped of all identifying information) to create an [issue](https://github.com/arcus/education_modules/issues) so that everyone using the repository knows we're working on a fix. In fact, if you feel comfortable, you, too, can [create an issue](https://github.com/arcus/education_modules/issues/new/choose)!

### Save Assets Well

Expand Down
Loading

0 comments on commit 032a62c

Please sign in to comment.