Module Quality Assurance Report for PR #2

Date: 2022-03-09
Reviewer: Rose Franzen
qa_template_version: 2.0.0
Name of Module: Data Visualization in Open Source Software
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/data_viz_open_source/data_visualization_in_open_source_software/data_visualization_in_open_source_software.md#1
Current Version of Module (use the latest commit value): ec9b30b

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources.
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• [ NA] A link is provided to run the code in binder
• [NA ] A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Module Quality Assurance Report for PR #34

Date: 2022-01-03
Reviewer: Meredith Lee
Name of Module: Command Line 101
Current Liascript URL: https://liascript.io/course/?https://raw.githubusercontent.com/arcus/education_modules/bash-scripting-101/bash_scripting_101/bash_scripting_101.md#1
Current Version of Module (use the latest commit value): a2689bc

Checklist Reports:

Structural Elements

• YAML top section filled in with name, email, language, narrator, title, and comment (blurb) filled out appropriately.
• YAML top section includes proper link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css).
• YAML top section has a version of at least 1.0.0 (first public version).
• Title is the first line and is the only level-1 header in the document.
• Overview section immediately follows Title, surrounded in div with class overview, and has filled in sections including an intro blurb, Estimated time to completion, Pre-requisites, Learning objectives, and Contents.
• Contents within Overview reflect accurately the sections and the links in the contents section work.
• Sections following Overview all have content (no pages with just header and no additional text / media material).
• Final section is Feedback.

Content

• Good amount of content, both in terms of the complexity/usefulness of the material covered and the time estimate
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• There are no tangents or mission creep in the module content, straying from the learning objectives.
• No betrayal of expectations: The module title, description, learning objectives, time estimate, and overview all accurately reflect the content of the module. A learner should be able to make an informed decision about whether or not to complete the module.
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• Unusual words, or words taking on a very specific meaning in context, are always defined for the user, either on the page (e.g. using footnotes) or with links to a definition/glossary. Provides pronunciation guides for especially unusual words of particular importance.
• Provides content in a variety of forms and styles: screencasts, text, webinars/lectures, practical exercises, etc. Whenever possible, multiple forms/styles should be incorporated in each module so learners have multiple avenues to the content.
• 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", say "Read this article to learn more about python.")
• Includes accurately formatted and functional link to feedback form.
• Spelling and grammar are correct.

Organization

• Clear, informative headers and sensible hierarchical structure (the TOC in the left margin should give a good overview of the content convered)
• Uses specially formatted highlight boxes consistently and appropriately
• Short, digestible pieces --- avoids long paragraphs and breaks long sections up with sub-headers

Formative assessment

• Frequent formative assessment in the form of knowledge checks and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Knowledge check questions and hands-on exercises relate directly to learning objectives

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text available for every image.
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted.

• description or quote, line ___ in file ____
• description or quote, line ___ in file ____
• description or quote, line ___ in file ____

Module Quality Assurance Report for PR #3

Date: 2022-03-28
Reviewer: Rose Franzen
qa_template_version: 2.0.0
Name of Module: Data Visualization in seaborn
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/data_viz_seaborn/data_visualization_in_seaborn/data_visualization_seaborn.md#1
Current Version of Module (use the latest commit value): ce9b192

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Module Quality Assurance Report for PR #63

Date: 2022-03-29
Reviewer: Joy Payton
qa_template_version: 2.0.0
Name of Module: Exploring the History of your Git Repository
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/git_history_of_project/git_history_of_project/git_history_of_project.md
Current Version of Module (use the latest commit value): 4f470c2

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Module Quality Assurance Report for PR #7

Date: 2021-12-02
Reviewer: Meredith Lee
Name of Module: Statistical Tests in Open Source Software
Current Liascript URL: (https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/statistical_tests/statistical_tests/statistical_tests.md#1)
Current Version of Module (use the latest commit value): 8305229

Checklist Reports:

Structural Elements

• YAML top section filled in with name, email, language, narrator, title, and comment (blurb) filled out appropriately.
• YAML top section includes proper link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/modules.css).
• YAML top section has a version of at least 1.0.0 (first public version).
• Title is the first line and is the only level-1 header in the document.
• Overview section immediately follows Title, surrounded in div with class overview, and has filled in sections including an intro blurb, Estimated time to completion, Pre-requisites, and Learning objectives.
• Sections following Overview all have content (no pages with just header and no additional text / media material).
• Final section is Feedback.

Content

• Good amount of content, both in terms of the complexity/usefulness of the material covered and the time estimate
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• There are no tangents or mission creep in the module content, straying from the learning objectives.
• No betrayal of expectations: The module title, description, learning objectives, time estimate, and overview all accurately reflect the content of the module. A learner should be able to make an informed decision about whether or not to complete the module.
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• Unusual words, or words taking on a very specific meaning in context, are always defined for the user, either on the page (e.g. using footnotes) or with links to a definition/glossary. Provides pronunciation guides for especially unusual words of particular importance.
• Provides content in a variety of forms and styles: screencasts, text, webinars/lectures, practical exercises, etc. Whenever possible, multiple forms/styles should be incorporated in each module so learners have multiple avenues to the content.
• 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", say "Read this article to learn more about python.")
• Includes accurately formatted and functional link to feedback form.
• Spelling and grammar are correct.

Organization

• Clear, informative headers and sensible hierarchical structure (the TOC in the left margin should give a good overview of the content convered)
• Uses specially formatted highlight boxes consistently and appropriately
• Short, digestible pieces --- avoids long paragraphs and breaks long sections up with sub-headers

Formative assessment

• Frequent formative assessment in the form of knowledge checks and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Knowledge check questions and hands-on exercises relate directly to learning objectives

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text available for every image.
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted.

• Intro to R, Additional Resources, line 254 in statistical_tests.md
• Intro to Python, Additional Resources, line 254 in statistical_tests.md
• data visualization in R and python, Additional Resources, line 256 in statistical_tests.md
• our explanation in the Intro to R module, Resources for Other Software, line 272 in statistical_tests.md

Currently the jupyter notebook for this module resides in a separate repo, which is unnecessary at this time (at least for python modules), and we want users to be able to easily access the materials.

Module Quality Assurance Report for PR #66

Date: 2022-03-20
Reviewer: Rose Hartman
qa_template_version: 2.0.0
Name of Module: Setting Up Git on Windows
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/git_setup_for_windows/git_setup_windows/git_setup_windows.md
Current Version of Module (use the latest commit value): b3d2f7b

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• [NA ] A link is provided to run the code in binder
• [NA ] A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• [ NA] Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• [NA ] Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

None

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

The screenshots in Python Code and Python Scripts would be better as gifs

Checking for compliance with QA template 2.0.0

Module Quality Assurance Report for PR #97

Date: 2022-05-18
Reviewer: Rose Hartman
qa_template_version: 2.0.0
Name of Module: Transforming Data in Python using Pandas
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/pandas_transform/pandas_transform/pandas_transform.md#1
Current Version of Module (use the latest commit value): 7b66a0f

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• links to other modules in prereqs

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Module Quality Assurance Report for PR #109

Date: 2022-05-18
Reviewer: Meredith Lee
qa_template_version: 2.0.0
Name of Module: Bash/Command Line 102
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/main/bash_command_line_102/bash_command_line_102.md#1
Current Version of Module (use the latest commit value): 3977796

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Module Quality Assurance Report for PR #55

Date: 2022-03-10
Reviewer: Elizabeth Drellich
qa_template_version: 2.0.0
Name of Module: Intro to Version Control
Current Liascript URL: https://liascript.io/course/?https://raw.githubusercontent.com/arcus/education_modules/rmh-git-intro/git_intro/git_intro.md#1
Current Version of Module (use the latest commit value): 7b1696e

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Frequent formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Module Quality Assurance Report for PR #60

Date: 2022-03-14
Reviewer: Rose Franzen
qa_template_version: 2.0.0
Name of Module: R Basics: Introduction
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/r_basics_introduction/r_basics_introduction/r_basics_introduction.md
Current Version of Module (use the latest commit value): f04f121

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

This is a list of open questions regarding the structure and general aesthetics of the modules. Please add anything else that you think of that I've missed.

• #16
• #17
• #18
• #19
• #21

Module Quality Assurance Report for PR #1

Date: 2021-11-16
Reviewer: Meredith Lee, taken over by Rose Hartman 12/2/2021
Name of Module: Data Visualization in ggplot2
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/data_visualization_ggplot2/data_visualization_in_ggplot2/data_visualization_ggplot2.md
Current Version of Module (use the latest commit value): 39045c9

Checklist Reports:

Structural elements

• YAML top section filled in with name, email, language, narrator, title, and comment (blurb) filled out appropriately.
• YAML top section includes proper link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/modules.css).
• #24
• Title is the first line and is the only level-1 header in the document.
• Overview section immediately follows Title, surrounded in div with class overview, and has filled in sections including an intro blurb, is this right for me?, Estimated time to completion, Pre-requisites, Learning objectives.
• Sections following Overview all have content (no pages with just header and no additional text / media material).
• Final section is Feedback.

Content

• Good amount of content, both in terms of the complexity/usefulness of the material covered and the time estimate
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• There are no tangents or mission creep in the module content, straying from the learning objectives.
• No betrayal of expectations: The module title, description, learning objectives, time estimate, and overview all accurately reflect the content of the module. A learner should be able to make an informed decision about whether or not to complete the module.
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• Unusual words, or words taking on a very specific meaning in context, are always defined for the user, either on the page (e.g. using footnotes) or with links to a definition/glossary. Provides pronunciation guides for especially unusual words of particular importance.
• provides content in a variety of forms and styles: screencasts, text, webinars/lectures, practical exercises, etc.
• 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", say "Read this article to learn more about python.")
• Includes accurately formatted and functional link to feedback form.
• Spelling and grammar are correct.

Organization

• Clear, informative headers and sensible hierarchical structure (the TOC in the left margin should give a good overview of the content convered)
• Uses specially formatted highlight boxes consistently and appropriately
• Short, digestible pieces --- avoids long paragraphs and breaks long sections up with sub-headers

Formative assessment

• Frequent formative assessment in the form of knowledge checks and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Knowledge check questions and hands-on exercises relate directly to learning objectives

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text available for every image.
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted.

• data visualization in open source software (prereqs)
• statistical tests (prereqs)
• intro to r (prereqs)
• download all the code for this module to run offline (lesson prep)
• binder link (lesson prep)
• data visualization in seaborn (additional resources)

Module Quality Assurance Report for PR #4

Date: 2021-11-21
Reviewer: Colleen Gaynor
Name of Module: Introduction to Python
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/intro_to_python/intro_to_python/intro_to_python.md#1
Current Version of Module (use the latest commit value): 1947f96

Checklist Reports:

Structural Elements

• YAML top section filled in with name, email, language, narrator, title, and comment (blurb) filled out appropriately.
• YAML top section includes proper link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/modules.css).
• YAML top section has a version of at least 1.0.0 (first public version).
• Title is the first line and is the only level-1 header in the document.
• Overview section immediately follows Title, surrounded in div with class overview, and has filled in sections including an intro blurb, Estimated time to completion, Pre-requisites, Learning objectives, and Contents.
• Contents within Overview reflect accurately the sections and the links in the contents section work.
• Sections following Overview all have content (no pages with just header and no additional text / media material).
• Final section is Feedback.

Content

• Good amount of content, both in terms of the complexity/usefulness of the material covered and the time estimate
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• There are no tangents or mission creep in the module content, straying from the learning objectives.
• No betrayal of expectations: The module title, description, learning objectives, time estimate, and overview all accurately reflect the content of the module. A learner should be able to make an informed decision about whether or not to complete the module.
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• Unusual words, or words taking on a very specific meaning in context, are always defined for the user, either on the page (e.g. using footnotes) or with links to a definition/glossary. Provides pronunciation guides for especially unusual words of particular importance.
• Provides content in a variety of forms and styles: screencasts, text, webinars/lectures, practical exercises, etc. Whenever possible, multiple forms/styles should be incorporated in each module so learners have multiple avenues to the content.
• 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", say "Read this article to learn more about python.")
• Includes accurately formatted and functional link to feedback form.
• Spelling and grammar are correct.

Organization

• Clear, informative headers and sensible hierarchical structure (the TOC in the left margin should give a good overview of the content convered)
• Uses specially formatted highlight boxes consistently and appropriately
• Short, digestible pieces --- avoids long paragraphs and breaks long sections up with sub-headers

Formative assessment

• Frequent formative assessment in the form of knowledge checks and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Knowledge check questions and hands-on exercises relate directly to learning objectives

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text available for every image.
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted.

• binder link, line 106 in file intro_to_python.md
• links for python interactive gif, line 149 in file intro_to_python.md
• spyder console gif, line 174 in intro_to_python.md
• binder link, line 198 in file intro_to_python.md

Module Quality Assurance Report for PR #74

Date: 2022-03-23
Reviewer: Joy Payton
qa_template_version: 2.0.0
Name of Module: Learning How to Learn Data Science
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/learning_to_learn/learning_to_learn/learning_to_learn.md#1
Current Version of Module (use the latest commit value): {click on the PR and get the clickable short link to the latest commit -- see quality_assurance_guide.md}

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• [N/A] A link is provided to run the code in binder
• [N/A] A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Module Quality Assurance Report for PR # 103

Date: 2022-05-13
Reviewer: Colleen Gaynor
qa_template_version: 2.0.0
Name of Module: Mll command line 101 updates
Current Liascript URL: {makes it easy for reviewers and authors to look at content as learners will}
Current Version of Module (use the latest commit value): e17fe50

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Module Quality Assurance Report for PR #69

Date: 2022-03-22
Reviewer: Rose Hartman
qa_template_version: 2.0.0
Name of Module: Tidy Data
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/tidy_data/tidy_data/tidy_data.md
Current Version of Module (use the latest commit value): fd7a578

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

None

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Module Quality Assurance Report for PR #57

Date: 2022-03-10
Reviewer: Elizabeth Drellich
qa_template_version: 2.0.0
Name of Module: Setting Up Git
Current Liascript URL: https://liascript.io/course/?https://raw.githubusercontent.com/arcus/education_modules/rmh-git-setup/git_setup/setting_up_git.md#1
Current Version of Module (use the latest commit value): 8b4b533

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/git_setup_for_windows/git_setup_windows/git_setup_windows.md, line 59 in file setting_up_git_mac_and_linux.md
• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Module Quality Assurance Report for PR #39

Date: 2022-03-21
Reviewer: Rose Hartman
qa_template_version: 2.0.0
Name of Module: Directories and file paths
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/directories_and_file_paths/directories_and_file_paths/directories_and_file_paths.md#1
Current Version of Module (use the latest commit value): 99375ea

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

None

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Module Quality Assurance Report for PR #46

Date: 2022-03-04
Reviewer: Rose Hartman
Name of Module: Types of Data Storage Models
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/data-storage-models/data_storage_models/data_storage_models.md#1
Current Version of Module (use the latest commit value): abf37ef

Checklist Reports:

Structural Elements

• YAML top section filled in with name, email, language, narrator, title, and comment (blurb) filled out appropriately.
• YAML top section includes proper link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css).
• YAML top section has a version of at least 1.0.0 (first public version).
• Title is the first line and is the only level-1 header in the document.
• Overview section immediately follows Title, surrounded in div with class overview, and has filled in sections including a short and focused intro blurb, an "Is this module right for me?" section that includes a longer description written in simple language, Estimated time to completion, Pre-requisites, and Learning objectives.
• N/A [ ] Contents within Overview reflect accurately the sections and the links in the contents section work.
• Sections following Overview all have content (no pages with just header and no additional text / media material).
• Final section is Feedback.

Content

• Good amount of content, both in terms of the complexity/usefulness of the material covered and the time estimate
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• There are no tangents or mission creep in the module content, straying from the learning objectives.
• No betrayal of expectations: The module title, description, learning objectives, time estimate, and overview all accurately reflect the content of the module. A learner should be able to make an informed decision about whether or not to complete the module.
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• Unusual words, or words taking on a very specific meaning in context, are always defined for the user, either on the page (e.g. using footnotes) or with links to a definition/glossary. Provides pronunciation guides for especially unusual words of particular importance.
• Provides content in a variety of forms and styles: screencasts, text, webinars/lectures, practical exercises, etc. Whenever possible, multiple forms/styles should be incorporated in each module so learners have multiple avenues to the content.
• 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", say "Read this article to learn more about python.")
• Includes accurately formatted and functional link to feedback form.
• Spelling and grammar are correct.

Organization

• Clear, informative headers and sensible hierarchical structure (the TOC in the left margin should give a good overview of the content convered)
• Uses specially formatted highlight boxes consistently and appropriately
• Short, digestible pieces --- avoids long paragraphs and breaks long sections up with sub-headers

Formative assessment

• Frequent formative assessment in the form of knowledge checks and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Knowledge check questions and hands-on exercises relate directly to learning objectives

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text available for every image.
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted.

Record a screencast to demonstrate the exercises in the Intro to Python module.

• barplots (counts of calssification type?)
• heatmap (correlations?)
• boxplots and distribution plots

I was copying over content from this module to update the ggplot2 module and I noticed a few little errors:

• line 186: missing alt text
• line 240: reference to wrong folder for code
• line 255: reference to wrong folder for code
• line 262: reference is to branch (and its the visualize branch as well, not the intro one), so I think it will break if/when that branch is deleted, although it's still working now
• the png and gif referenced in line 262 appear to not be in the media folder on main
• line 276: I think the last file name should be transform_exercises.rmd rather than transform.rmd
• line 671: reference to wrong folder for code

Module template still mentions pangeo binder in Lesson Preparation. I propose we replace that content with two sections, one for typical R setup and one for typical python setup.

I also think we should consider centralizing the materials (i.e. media, like screenshots) for these sections, so that they don't need to be copied individually into each module's media folder, and so we can update them across the board with one change if needed. I haven't look at the python setup procedure, but for R materials, I propose we add a media folder to the education_r_environment repo and point to that for all the screenshots etc to be used in modules in the Lesson Preparation section. Module-specific media would of course stay in that module's media folder.

I also think it would be great to use YAML variables for any folders or files that need to get referenced in Lesson Preparation so that we can just blindly copy-paste that whole section from the template and use it unchanged in a new module, just updating the YAML. (For an example, see the new PR for the Data visualization in ggplot2 module, where I tried this out.)

@pm0kjp and @leemc-data-ed in particular, since the two of you have been writing the intro R and intro python modules, respectively.

Module Quality Assurance Report for PR #103

Date: 2022-05-24
Reviewer: Joy Payton
qa_template_version: 2.0.0
Name of Module: Bash 101
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/mll-command-line-101-updates/bash_command_line_101/bash_scripting_101.md#1
Current Version of Module (use the latest commit value): 6fdc935

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

To create a new QA issue, copy and paste the text of the quality assurance template into the description of a new issue.

Further instructions on setting up a quality assurance issue can be found in this QA how-to guide

Doing another quick QA on this module since I think it was reviewed under the previous template

Module Quality Assurance Report for PR #65

Date: 2022-03-18
Reviewer: Rose Franzen
qa_template_version: 2.0.0
Name of Module: R Basics: Visualizing Data With ggplot2
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/r_basics_visualize_data/r_basics_visualize_data/r_basics_visualize_data.md#1
Current Version of Module (use the latest commit value): 09c05ed

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Module Quality Assurance Report for PR #[PR number here]

Date: [yyyy-mm-dd]
Reviewer: [your name]
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]
Current Version of Module (use the latest commit value): [click on the PR and get the clickable short link to the latest commit -- add screenshot here]

Checklist Reports:

Structural Elements

• YAML top section filled in with name, email, language, narrator, title, and comment (blurb) filled out appropriately.
• YAML top section includes proper link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css).
• YAML top section has a version of at least 1.0.0 (first public version).
• Title is the first line and is the only level-1 header in the document.
• Overview section immediately follows Title, surrounded in div with class overview, and has filled in sections including a short and focused intro blurb, an "Is this module right for me?" section that includes a longer description written in simple language, Estimated time to completion, Pre-requisites, and Learning objectives.
• Contents within Overview reflect accurately the sections and the links in the contents section work.
• Sections following Overview all have content (no pages with just header and no additional text / media material).
• Final section is Feedback.

Content

• Good amount of content, both in terms of the complexity/usefulness of the material covered and the time estimate
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• There are no tangents or mission creep in the module content, straying from the learning objectives.
• No betrayal of expectations: The module title, description, learning objectives, time estimate, and overview all accurately reflect the content of the module. A learner should be able to make an informed decision about whether or not to complete the module.
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• Unusual words, or words taking on a very specific meaning in context, are always defined for the user, either on the page (e.g. using footnotes) or with links to a definition/glossary. Provides pronunciation guides for especially unusual words of particular importance.
• Provides content in a variety of forms and styles: screencasts, text, webinars/lectures, practical exercises, etc. Whenever possible, multiple forms/styles should be incorporated in each module so learners have multiple avenues to the content.
• 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", say "Read this article to learn more about python.")
• Includes accurately formatted and functional link to feedback form.
• Spelling and grammar are correct.

Organization

• Clear, informative headers and sensible hierarchical structure (the TOC in the left margin should give a good overview of the content convered)
• Uses specially formatted highlight boxes consistently and appropriately
• Short, digestible pieces --- avoids long paragraphs and breaks long sections up with sub-headers

Formative assessment

• Frequent formative assessment in the form of knowledge checks and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Knowledge check questions and hands-on exercises relate directly to learning objectives

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text available for every image.
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted.

• description or quote, line ___ in file ____
• description or quote, line ___ in file ____
• description or quote, line ___ in file ____

Module Quality Assurance Report for PR #100

Date: 2022-04-27
Reviewer: Colleen Gaynor
qa_template_version: 2.0.0
Name of Module: SQL Basics
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/sql_basics/sql_basics/sql_basics.md#1
Current Version of Module (use the latest commit value): bcda3ed

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• I am not really sure about this, but the only internal link referenced is in the Prerequisite section for [Demystifying Sequel]

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Checking for compliance with QA template 2.0.0

Module Quality Assurance Report for PR #5

Date: 2021-11-13
Reviewer: Joy Payton
Name of Module: Introduction to R and RStudio
Current Liascript URL: https://liascript.io/course/?https://raw.githubusercontent.com/arcus/education_modules/278c7ee1d0212dd85b5bcc014bc3cb19970f108b/intro_to_r_rstudio/intro_to_r_rstudio.md#1
Current Version of Module (use the latest commit value): 3314002

Checklist Reports:

Structural Elements

• YAML top section filled in with name, email, language, narrator, title, and comment (blurb) filled out appropriately.
• YAML top section includes proper link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/modules.css).
• YAML top section has a version of at least 1.0.0 (first public version).
• Title is the first line and is the only level-1 header in the document.
• Overview section immediately follows Title, surrounded in div with class overview, and has filled in sections including an intro blurb, Estimated time to completion, Pre-requisites, Learning objectives, and Contents.
• Contents within Overview reflect accurately the sections and the links in the contents section work.
• Sections following Overview all have content (no pages with just header and no additional text / media material).
• Final section is Feedback.

Content

• Good amount of content, both in terms of the complexity/usefulness of the material covered and the time estimate
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• There are no tangents or mission creep in the module content, straying from the learning objectives.
• No betrayal of expectations: The module title, description, learning objectives, time estimate, and overview all accurately reflect the content of the module. A learner should be able to make an informed decision about whether or not to complete the module.
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• Unusual words, or words taking on a very specific meaning in context, are always defined for the user, either on the page (e.g. using footnotes) or with links to a definition/glossary. Provides pronunciation guides for especially unusual words of particular importance.
• Provides content in a variety of forms and styles: screencasts, text, webinars/lectures, practical exercises, etc. Whenever possible, multiple forms/styles should be incorporated in each module so learners have multiple avenues to the content.
• 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", say "Read this article to learn more about python.")
• Includes accurately formatted and functional link to feedback form.
• Spelling and grammar are correct.

Organization

• Clear, informative headers and sensible hierarchical structure (the TOC in the left margin should give a good overview of the content convered)
• Uses specially formatted highlight boxes consistently and appropriately
• Short, digestible pieces --- avoids long paragraphs and breaks long sections up with sub-headers

Formative assessment

• Frequent formative assessment in the form of knowledge checks and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Knowledge check questions and hands-on exercises relate directly to learning objectives

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text available for every image.
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted.

• image link, line 148 in file intro_to_r_rstudio.md
• image link, line 164 in file intro_to_r_rstudio.md
• image link, line 225 in file intro_to_r_rstudio.md
• image link, line 232 in file intro_to_r_rstudio.md
• image link, line 254 in file intro_to_r_rstudio.md
• image link, line 260 in file intro_to_r_rstudio.md
• image link, line 266 in file intro_to_r_rstudio.md
• image link, line 349 in file intro_to_r_rstudio.md

Module Quality Assurance Report for PR #96

Date: 2022-04-18
Reviewer: Elizabeth Drellich
qa_template_version: 2.0.0
Name of Module: Using the REDCap API
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/using_redcap_api/using_redcap_api/using_redcap_api.md#1
Current Version of Module (use the latest commit value): 676ff15

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Module Quality Assurance Report for PR #43

Date: 2022-03-11
Reviewer: Elizabeth Drellich
qa_template_version: 2.0.0
Name of Module: R Basics: Transforming Data With dplyr
Current Liascript URL: https://liascript.io/course/?https://raw.githubusercontent.com/arcus/education_modules/r_basics_transform_data/r_basics_transform_data/r_basics_transform_data.md#1
Current Version of Module (use the latest commit value): c1298ab

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Module Quality Assurance Report for PR #59

Date: 2022-03-14
Reviewer: Joy Payton
qa_template_version: 2.0.0
Name of Module: Creating a Git Repository
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/git_creation_and_tracking/git_creation_and_tracking/git_creation_and_tracking.md
Current Version of Module (use the latest commit value): 0f46503

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

None!

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Module Quality Assurance Report for PR #72

Date: 2022-03-22
Reviewer: Meredith Lee
qa_template_version: 2.0.0
Name of Module: Demystifying SQL
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/demystifying_sql/demystifying_sql/demystifying_sql.md#1
Current Version of Module (use the latest commit value): 0a68223

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

• #160
• #161
• #162

Module Quality Assurance Report for PR #113

Date: 2022-05-18
Reviewer: Rose Franzen
qa_template_version: 2.0.0
Name of Module: Demystifying Python
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/update-intro-to-python/demystifying_python/demystifying_python.md#1
Current Version of Module (use the latest commit value): c3a8c26

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• [] A link is provided to run the code in binder
• [] A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• [] Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• [] Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• clickable gif, line 147 in file demystifying_python.md
• clickable gif, line 182 in file demystifying_python.md
• clickable gif, line 269 in file demystifying_python.md

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Doing another quick QA since this module was reviewed under the old template

Module Quality Assurance Report for PR #82

Date: 2022-03-24
Reviewer: Meredith Lee
qa_template_version: 2.0.0
Name of Module: Statistical tests in open source software
Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/check-statistical-tests/statistical_tests/statistical_tests.md#1
Current Version of Module b8979c0

Checklist Reports:

Directory structure

• Folder and file names use lowercase and underscores (no dashes)
• Main module directory folder name is identical to the name of the module content markdown file.
• Images, videos, and other audio-visual assets are saved within a media folder within the module directory

Module Organization

• YAML is at the very top of the file
  • author name
  • email
  • 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
  • module_template_version number is up to date with the current sample module -- if not, the module should be brought in line with any changes that have occurred to the module template before continuing with QA
  • language
  • narrator
  • comment appropriately filled out
  • long_description appropriately filled out
  • learning_objectives appropriately filled out
  • link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• Title is the first line after the end of the YAML
  • only level-1 header in the entire document.
• Overview section immediately following Title
  • surrounded in div with class overview
  • Comment is at the top of the Overview, linked from YAML rather than rewritten
  • "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • Learning objectives linked from learning_objectives YAML rather than rewritten
• All sections following Overview have content (no pages with just header and no additional text / media material).
• All quizzes start with a level 2 or 3 header. If there is only one quiz in the module, it is labelled "Quiz", or if there are multiple, each header is structured as "Quiz: label" where "label" is a short (~ 1-2 words) description of the content covered in the question(s). E.g., "Quiz: Scatterplots"
• Educational content ends with a section of additional resources, both ours and outside sources
• Final section is Feedback.
  • Learning objectives linked from YAML rather than rewritten
  • Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• Complexity of the material covered seems appropriate given prerequisites.
• Time estimate appears accurate for a learner of the targeted level.
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• The module title, blurb/comment, and long description accurately reflect the content of the module.
• Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• 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", say "Read this article to learn more about python.")
• 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 for a place to keep track of internal references that will need to be updated.)
• Spelling and grammar are correct.

Code availability

If the module includes code that learners may want to run:

• A link is provided to run the code in binder
• A link to the raw code and any other necessary materials (e.g., data) is provided for learners who prefer to work on their own machine

Formative assessment

• Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Quiz questions and hands-on exercises relate directly to learning objectives
• Every learning objective has at least one associated question
• Questions can be answered based on the content within the module alone; learners should not need to have read or consulted any of the linked external resources

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text is specified for each image. For help writing and assessing descriptive alt text, see this alt text image concepts guide and this alt text decision tree.
  • Alt text never starts with "photo of", "screenshot of", "image of", or any other information describing the medium of the image (the only exception to this is when describing data visualization -- it is appropriate to start alt text with "a scatterplot...", for example)
  • Alt text is written to provide the same relevant information to someone using a screen-reader as provided to someone who accesses the information visually
    • E.g., rather than "Screenshot of PR with multiple commits", alt text says 'On a pull request, the PR comment appears at the top. Below, commits appear as their commit summary followed by commit hash.'
  • For any images that provide a function when clicked, the alt text describes the function of the button rather than describes the visual aspects of the button.
    • E.g., if an image of the GitHub logo is intended to be clicked on to access the education_modules repository, it is labelled "arcus education_modules GitHub repository" rather than "GitHub logo". If this information is also accompanied by a descriptive link in the text, however, then a blank alt tag is appropriate.
  • Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • Purely decorative visuals (other examples) have a blank alt text label: ![""](image_path) Note that this is not the same as not specifying alt text at all: ![](image_path)
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR Approval

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted. Prior to approving the PR and merging to main, all references should be updated in a new commit.

(If there are none, the reviewer can either check off the boxes below without making any edits, or can remove the items below and replace with the text "None".)

• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}
• {description or quote, line ___ in file ____}

Just Before Approval

• Once there are no more commits to be made, get the newest commit value for the PR and update the commit value ("Current Version of Module:") at the top of this document.

Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.

Module Quality Assurance Report for PR #6

Date: 2021-11-13
Reviewer: Joy Payton
Name of Module: Reproducibility, Generalizability, and Reuse: How Technology Can Help
Current Liascript URL: https://liascript.io/course/?https://raw.githubusercontent.com/arcus/education_modules/reproducibility/reproducibility/reproducibility.md
Current Version of Module (use the latest commit value): 7cba256

Checklist Reports:

Structural Elements

• YAML top section filled in with name, email, language, narrator, title, and comment (blurb) filled out appropriately.
• YAML top section includes proper link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/modules.css).
• YAML top section has a version of at least 1.0.0 (first public version).
• Title is the first line and is the only level-1 header in the document.
• Overview section immediately follows Title, surrounded in div with class overview, and has filled in sections including an intro blurb, Estimated time to completion, Pre-requisites, Learning objectives, and Contents.
• Contents within Overview reflect accurately the sections and the links in the contents section work.
• Sections following Overview all have content (no pages with just header and no additional text / media material).
• Final section is Feedback.

Content

• Good amount of content, both in terms of the complexity/usefulness of the material covered and the time estimate
• Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• Every learning objective is covered in the module content.
• There are no tangents or mission creep in the module content, straying from the learning objectives.
• No betrayal of expectations: The module title, description, learning objectives, time estimate, and overview all accurately reflect the content of the module. A learner should be able to make an informed decision about whether or not to complete the module.
• Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• Unusual words, or words taking on a very specific meaning in context, are always defined for the user, either on the page (e.g. using footnotes) or with links to a definition/glossary. Provides pronunciation guides for especially unusual words of particular importance.
• Provides content in a variety of forms and styles: screencasts, text, webinars/lectures, practical exercises, etc. Whenever possible, multiple forms/styles should be incorporated in each module so learners have multiple avenues to the content.
• 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", say "Read this article to learn more about python.")
• Includes accurately formatted and functional link to feedback form.
• Spelling and grammar are correct.

Organization

• Clear, informative headers and sensible hierarchical structure (the TOC in the left margin should give a good overview of the content convered)
• Uses specially formatted highlight boxes consistently and appropriately
• Short, digestible pieces --- avoids long paragraphs and breaks long sections up with sub-headers

Formative assessment

• Frequent formative assessment in the form of knowledge checks and/or hands-on exercises
• Clear explanations available after questions unless the nature of the question itself or answer options makes it unnecessary (e.g. a T/F question may not always require follow-up explanation)
• Knowledge check questions and hands-on exercises relate directly to learning objectives

Videos and images

• Screencasts cover a single coherent task so the recording is a short as is feasible. To demonstrate more than one related task, include several short screencasts in succession rather than recording one long screencast.
• Subtitles available for every recording with audio.
• Alt text available for every image.
• Important visuals (in video, image, or gif) are always described in the audio or in accompanying text.
  • For example, in a screencast, instead of just, "And then click here," provide description that could help scaffold someone without visual access like, "And then click on the button that says 'Run' in the top-right corner of the screen". Be sure to make use of text cues when available (e.g. button labels), not just visual signals like color or location.
  • When important content is conveyed in a visual, describe the key elements. For example, "Running this query produces the table below. It displays the first 5 rows by default, and columns for ID, encounter ID, diagnosis, and outcome."
  • When including a data visualization, describe important features, such as both axis labels and visible trends in the data. For example, "Here's a scatterplot showing number of encounters on the y-axis and age on the x-axis. All 183 patients from our sample are represented here, and it looks like a weak positive trend, with older patients being more likely to have had more encounters. There are a few important outliers, though, such as this patient at about 6 months old with more than 20 encounters already."
  • When visual information is repeated with minimal changes, it's fine to indicate that without providing a full description again. For example, "And here's the updated table, filtered to only show patients who have been seen in the last 2 years."
  • When important visual information in a video is too complex to include sufficient audio description (i.e. it would slow the content down so much as to impair its utility), an alternative video file should be provided with audio descriptions included.
• Color is never the sole method for distinguishing visual content (including in data visualizations).

Branch References to Change prior to PR

List here any internal references (stated or hyperlinked) that work now because they refer to the named branch, but will not work once this is on the main branch and the named branch is deleted.

• (none noted by reviewer JP)

• @pm0kjp will revamp R module(s) using more battle tested material (from Stephan for example) and re-QA by EOY

• @pm0kjp will also take a look at the front README.md, how_to (better name?!?!) and qa readmes to improve (aside: add 'make sure learners know how to download source code'), with the same delivery date (Dec 31).

• @pm0kjp will come up with an aspirational modules-by-month schedule and share it around by Dec 10 EOB.

• @pm0kjp will reach out to IS to get an email address -- [email protected] or similar....

• @rosemm will finish the ggplot2 module super extra done and finish up the QA, taking over for Meredith, probably finished by EOB Dec 6

• @rosemm will work on the Seaborn module throughout December

• @franzenr will work on the review of Intro to Data Viz and have it entirely reviewed by Dec. 8

• @leemc-data-ed will work on the review of Tests in Open Source and have it entirely reviewed by Dec. 8

• @cgaynor79 will loop in other team members for questions about content complexity etc. for the Intro to Python module and also will consider making some issues that might help us elucidate the QA process (what was difficult to make a ruling on and can we make the steps of that more explicit) by Dec. 8