[ ] 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
[ ] Front matter is at the very top of the file
[ ] Check included front matter fields against the front matter checklist to make sure all necessary fields are included. In addition, check the following details:
[ ] current_version_description is a short, present-tense text fragment without bullets, and gives a learner-centric quick overview of version changes from the learner perspective
[ ] module_type should be standard
[ ] estimated_time_in_minutes should be a number 0-60
[ ] version_history contains 1-3 past versions with bulleted links to commit-specific documents, unless this is an initial version of a module, in which case version_history can be empty.
[ ] imports macros (currently this line should read import: https://raw.githubusercontent.com/arcus/education_modules/main/_module_templates/macros.md)
[ ] Title is the first line after the end of the front matter
[ ] only level-1 header in the entire document.
[ ] Overview section immediately following Title, using the @overview macro
[ ] 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
[ ] Final section is Feedback, using the @feedback macro
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)
[ ] 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
If the module includes code that learners may want to run:
[ ] A link is provided to run the code in the cloud
[ ] 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 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:  Note that this is not the same as not specifying alt text at all: 
[ ] 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
Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.
drelliche
commented
1 year ago
Module Quality Assurance Report for PR https://github.com/arcus/education_modules/pull/459
Date: 2023-08-03 Reviewer: Elizabeth Drellich qa_template_version: 2.0.0 Name of Module: Python Basics: Functions, Methods, and Variables Current Liascript URL: https://liascript.github.io/course/?https://raw.githubusercontent.com/arcus/education_modules/python_basics_functions_methods_variables/python_basics_variables_functions_methods/python_basics_variables_functions_methods.md#1
Checklist Reports:
Directory structure
mediafolder within the module directoryModule Organization
standardimport: https://raw.githubusercontent.com/arcus/education_modules/main/_module_templates/macros.md)@overviewmacro@feedbackmacroModule Content
Code availability
If the module includes code that learners may want to run:
Formative assessment
Videos and images
Note that this is not the same as not specifying alt text at all: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".)
Just Before Approval
Congratulations! You can now approve the PR, merge to main, and close (not delete) this issue.