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

[x] YAML top section filled in with name, email, language, narrator, title, and comment (blurb) filled out appropriately.
[x] YAML top section includes proper link to CSS (currently https://chop-dbhi-arcus-education-website-assets.s3.amazonaws.com/css/styles.css).
[x] YAML top section has a version of at least 1.0.0 (first public version).
[x] Title is the first line and is the only level-1 header in the document.
[x] 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.
[x] Contents within Overview reflect accurately the sections and the links in the contents section work.
[x] Sections following Overview all have content (no pages with just header and no additional text / media material).
[x] Final section is Feedback.

Content

[x] Good amount of content, both in terms of the complexity/usefulness of the material covered and the time estimate
[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] There are no tangents or mission creep in the module content, straying from the learning objectives.
[x] 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.
[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] Includes accurately formatted and functional link to feedback form.
[x] Spelling and grammar are correct.

Organization

[x] 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
[x] Short, digestible pieces --- avoids long paragraphs and breaks long sections up with sub-headers

Formative assessment

[x] Frequent formative assessment in the form of knowledge checks 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] 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.
[x] Alt text available for every image.
[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

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 __

I made most of the changes we talked through in our meeting in terms of the content and most formatting. I think the only outstanding things now are to figure out how to best resize images.

This is looking great! There are just a couple of formatting things and a couple of content things, but I think it's really close.

For the formatting stuff, I think it's just liascript being fussy-- I'm happy to just fix it if that's okay with you. Some of the quizzes still aren't displaying correctly, and using certain symbols seems to mess up the formatting.

For the content:

I'd recommend expanding some of the alt text for images, and really get as descriptive as possible (within reason). The guideline I'm trying to follow is that someone who can't see the image should get a pretty good sense of what it's trying to convey.
I think certain terms, like "Linux", "Unix", "executable files" could be defined, either in the text or in a glossary at the end. The abbreviation "CLI" also needs to be spelled out at least once (unless it's there and I just missed it, which is totally possible).

And then I think that the "Proceed with caution" warning you have on line 207, in the Permissions section, would be perfect to go into an "Important" highlight box. To do that, you use

. There is a section on how to use the highlight boxes in the sample template (but you have to look at the raw file to see anything useful!). I can also do this if you'd prefer.

Thanks @leemc-data-ed I am totally comfortable with you making those formatting changes and I will let you know once I've added those content and accessibility changes.

@leemc-data-ed incorporated some more changes, grateful as always for your feedback!

Your changes look great! I made the quizzes so that the explanations come up after the learner submits the answer, fixed the weirdness with the symbols (I can't figure out why it's happening, but surrounding them in backticks fixes it), and adjusted the widths of the images on in the Commands page so that they're the same size. Check it out and let me know what you think!

looks great, thanks so much for working through the technical issues!

should I close this issue and merge the branch?

We have to get the PR approved before we can merge, I want one more set of eyes too look over everything and make sure there isn't anything we missed, then we can approve and merge!

Hi! I looked over this module as well, since Meredith requested some fresh eyes :) Overall I really like it! It does an excellent job of staying concise and approachable while still covering quite a lot of ground, which is a hard balance to strike. Really awesome work here, and thank you to both of you for doing this! I'm on the fence about whether or not to just approve and publish as-is, because while I think it's probably good enough already, I do see a couple opportunities to make it stronger. I'm happy to leave that call up to you, though: If you're ready to just be done, you have my blessing! If you have a little steam left in you for more edits, though, here are my suggestions:

I really like the learning objectives, and right now it feels to me like they're being well-addressed, with the possible exception of the first ("Describe what bash scripting is and why they might want to learn it for data management and research"). This is covered in the material, but maybe too briefly, especially for folks that are brand new to shell. To shore this up, I would recommend adding a bit of very high-level overview at the beginning (e.g. what does "shell" even mean? https://www.geeksforgeeks.org/difference-between-shell-and-kernel/ might be a useful link, and/or perhaps a short bit to disambiguate the terms "shell," "bash," and "CLI"), and the addition of some concrete examples of bash scripting for research applications (e.g. you can use a shell script to call multiple other programs, like R and python, to build pipelines that move across other pieces of software; you will likely have to use shell scripting if you want to take advantage of high performance computing; you get more control over valuable tools like git, docker, etc. if you can use the command line) to give folks an idea of when they would use bash. I think those additions would tie a bow on the overview you've got there already, and bring it the last little bit of the way to meeting that first learning objective.
This is perhaps more of a style thing, but I noticed a few points in the module where you described CLI/bash as "easy" or "intuitive" --- I understand the urge to do this (I have the same impulse), to try to convince learners that the material is approachable and they can learn it, not to be intimidated. But I try to avoid that language myself because I also know that it can backfire; for someone who's new to the content and maybe feeling like they don't really get it yet, reading that it should be easy can double their impostor syndrome... My own strategy to avoid doing this is to try to focus instead on objective features of the thing I'm teaching (rather than subjective assessment), so I might say something like "If you're new to bash, it can feel like there's a lot to learn, but you really only need a handful of key commands to get started. Here's a list of the most commonly used bash commands, so just focus on these to start and you'll be surprised how much you can do!" or "One thing that's nice about using the command line is that it's probably all set up and ready to go on your computer, even if you've never used it before. There's generally no separate download or installation process you need to go through, you can just open the command line interface and try it out." So, generally, trying to focus on things like "it's quick to get started" or "it's similar to something you've already learned" or "there's a limited set you can focus on and ignore the rest to not get overwhelmed" helps me to avoid using words like "easy" and "intuitive", despite the strong urge to do so. :)
This is a tiny change, but in the glossary, it says "Bash is one type of Linux.", which makes it sound like bash is an OS, which isn't quite right. I would revise this to something like "Bash is the most common shell for Linux".

In addition to my earlier offer to just let it be done and approve as-is (which is genuine! I think it's a very solid module already.), I also want to mention that, if you want to pursue some of these changes, I would be more than happy to offer more concrete edit suggestions, i.e. push a commit with some changes you could use or not. I know it can be exhausting to interpret other people's suggestions for edits and generate new content vs. just evaluating some concrete edits provided as suggestions, and I would be very happy to share the lift on this! :) Just let me know.

Thank you for your thoughtful and well-explained feedback @rosemm. I tried incorporating some of your changes but I'd be grateful for more explicit help in making the distinction between shell and kernel because I think it is an important one but I am having trouble weaving it in elegantly. Thank you again!

Sure thing! I ran into the same problem you did trying to figure out where to squeeze it in, so I tried doing a slight rearrange of the structure in that first section to accommodate it. Basically, I broke your list into two parts (the bits that answer "what is shell scripting" vs the bits that answer "when would I use it"), and then popped in a "learnmore" box about the term "shell" at the end of the first part, since that seemed like the right moment for it. Here's the commit: c97afd3 Feel free to take what works for you and leave what doesn't, of course! P.S. When I opened the markdown file I did catch two little formatty things I hadn't seen when I was reviewing the module earlier: Ideally there should be a period at the end of each image's alt text, so I put those in, and the content you had under "is this module right for me" in the overview should be saved in the YAML as long_description, so I moved it up there. I put those changes in separate commits, to keep things tidy, so you'll see a string of three commits from me today.

@rosemm looks great thank you, I really appreciate you weaving everything together!

@nafeldman so I needed to go back in and fix some formatting weirdness with the quizzes-- now the extra explanation text will only come up once the learner has selected the correct answer.

I also made some minor tweaks to the language in a couple of places, to try to avoid using words like "easy" or other potentially minimizing words as Rose suggested and to clarify things in a couple of places. Take a look and let me know if I missed the mark on anything! Otherwise, I think we're good, and once I get your final okay, I'll approve and merge :)

Thanks again for all your awesome work on this!

@leemc-data-ed LGTM! feel free to merge :)

Merged with main, closing this issue!

arcus / education_modules

QA bash-scripting-101 #35