QA setting up git

[drelliche]

Module Quality Assurance Report for PR https://github.com/arcus/education_modules/pull/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): https://github.com/arcus/education_modules/pull/57/commits/8b4b53370226665a032f431aa1475294a1403e8b

Checklist Reports:

Directory structure

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

Module Organization

• [x] YAML is at the very top of the file
  • [x] author name
  • [x] email
  • [x] 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
  • [x] 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
  • [x] language
  • [x] narrator
  • [x] comment appropriately filled out
  • [x] long_description appropriately filled out
  • [x] learning_objectives appropriately filled out
  • [x] link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css)
  • [x] script to Font Awesome kit (currently https://kit.fontawesome.com/83b2343bd4.js)
• [x] Title is the first line after the end of the YAML
  • [x] only level-1 header in the entire document.
• [x] Overview section immediately following Title
  • [x] surrounded in div with class overview
  • [x] Comment is at the top of the Overview, linked from YAML rather than rewritten
  • [x] "Is this module right for me?" contents linked from long_description YAML rather than rewritten
  • [x] "Estimated time to completion" contents linked from estimated_time YAML rather than rewritten
  • [x] Prerequisites listed and do not require learner to have specifically attained those skills through any of our other modules.
  • [x] Learning objectives linked from learning_objectives YAML rather than rewritten
• [x] All sections following Overview have content (no pages with just header and no additional text / media material).
• [x] 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"
• [x] Educational content ends with a section of additional resources, both ours and outside sources
• [x] Final section is Feedback.
  • [x] Learning objectives linked from YAML rather than rewritten
  • [x] Feedback link is updated appropriately to automatically fill in the module name when clicked by learner.

Module Content

• [x] Complexity of the material covered seems appropriate given prerequisites.
• [x] Time estimate appears accurate for a learner of the targeted level.
• [x] Clearly defined learning objectives using strong, descriptive verbs. (See Bloom's taxonomy for ideas.)
• [x] Every learning objective is covered in the module content.
• [x] All major topics covered are represented by a learning objective -- there's no significant knowledge imparted that isn't specified in the learning objectives
• [x] The module title, blurb/comment, and long description accurately reflect the content of the module.
• [x] Headers are informative and follow a sensible hierarchical structure (the TOC in the left margin should give a good overview of the content covered)
• [x] Avoids unclear language: unexplained idioms or references, unexplained acronyms, unnecessary technical language.
• [x] 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.
• [x] Provides pronunciation guides for any especially unusual words of particular importance (a common example is package names, such as dplyr)
• [x] Avoids unnecessarily gendered language (e.g. uses "they" singular rather than "he or she" for an unknown person).
• [x] Informative link text (e.g. instead of "To learn more about python, click here", say "Read this article to learn more about python.")
• [x] Uses specially formatted highlight boxes consistently and appropriately
• [x] Short, digestible pieces --- avoids long paragraphs and breaks long sections up with sub-headers
• [x] 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.)
• [x] Spelling and grammar are correct.

Code availability

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

• [x] A link is provided to run the code in binder
• [x] 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

• [x] Sufficient formative assessment in the form of quizzes and/or hands-on exercises
• [x] 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)
• [x] Quiz questions and hands-on exercises relate directly to learning objectives
• [x] Every learning objective has at least one associated question
• [x] 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

• [x] 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.
• [x] Subtitles available for every recording with audio.
• [x] 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.
  • [x] 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)
  • [x] 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.'
  • [x] 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.
  • [x] Alt text is ideally a maximum of 125 characters, or as close to this as possible.
  • [x] 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)
• [x] 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.
• [x] 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".)

• [x] 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
• [x] {description or quote, line _ in file __}
• [x] {description or quote, line _ in file __}

Just Before Approval

• [x] 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.

[drelliche]

Observations and comments @rosemm

• folder is git_setup but markdown is setting_up_git.md
• version 0.0.1 should be 1.0.0
• line 94: GitHub's instructions link needs () instead of [] around url
• Proxy help: how will a user know if they need to use a proxy? Will they get a warning?
• Lots of modules have a "lesson preparation" section, I'm not sure if one makes sense for this module, but it might be helpful/reassuring to have an instruction to open the command line interface and start entering commands (i.e. you don't have to navigate to anywhere else).
• In several places I see "git" and I'm unsure if it should be capitalized. I've been sticking to either "Git" or git but avoiding "git". I'm not sure if that is something I made up or a convention that anyone agrees with me on so feel free to say "no that's silly."

[drelliche]

Further thoughts after talking with @pm0kjp:

We want to make sure Windows and Windows via Virtual Desktop Interface users can follow along, and it seems that they will need to be in the Git Bash app instead of the cmd app. It seems like that information/tutorial would best go in this module because even though they don't need cd and ls commands yet, this is all part of the set-up.

It does seem like this might be a 10 minute module for everyone except Windows users, for whom it is... longer.

[drelliche]

Let's change the name to "... for Mac and Linux" and remove the Windows instructions. Then we can point at the beginning of each setup module to the other if people find themselves in the wrong one.

[rosemm]

Okay, awesome! Thanks for the lovely suggestions, @drelliche. I've pushed the requested changes, so I think it's ready now.

[drelliche]

@rosemm Looks good! A few new/last things:

• folder and .md file should both be "setting_up_git_for_mac_and_linux"
• The link about how to tell if you are on a proxy seems sketchy (not its information, just its high add content). It is clearly the top google hit, but I've been looking for a better link, and am leaning towards just telling people to google it themselves? Maybe that is worse?
• @pm0kjp suggested adding a "try this, but also if you have problems talk to your own institution's tech support because they might have put up very high barriers to downloading things" warning, probably on page 2 in case they have to install Git.
• Add a link in the overview to the Windows version (and vice versa) in case people are accidentally in the wrong spot.

[rosemm]

@drelliche Good call, thanks! I found a classier link for the proxy example and re-worked the text a bit. Lemme know what you think. I also fixed the other issues you mentioned.

[drelliche]

@rosemm I love the new warnings and advice to go to IT, I'll be copying them to the Windows version too.

One typo: line 77 "if you computer is was issued"

After that I think all that is left is the correct link and merging!

[rosemm]

Ah, good catch! Thank you! Okay, fixed typo and link, and re-pushed! 🙌