2021-02 review of lesson text, general notes

[mikerenfro]

Help Wanted to Fix:

• "Utilize" could be "use" throughout. (Use, not utilize #353)
• Sometimes we emphasize terms with italics, sometimes with boldface. "The cloud" on 11-hpc-intro is bold, and "The cloud" on 12-cluster is italics. Any significance to the difference? Any preference on just using one?
• Should images be linked as "../fig/" instead of "fig/" ?
• Consistent use of "log in to" versus "log into", "log on to", "logon to", "login to"? ("log in to" consistently #354)
• Check notation for schedulers like "Slurm" instead of "SLURM" (Fix slurm notation #351).
• Capitalize Environment Modules throughout. Other uses of "module" can probably be lowercase.
• Some sbatch lines have two spaces between the command and the job script name. (Fixing extra spaces after sbatch commands #355)
• Decide on capitalization rules for headings. I've title-cased everything in 16-parallel, but I don't think that matches the rest of the episodes. (Fix header title casing #352)
  • The Carpentries Style Guide stipulates Title Case.
• Consistently format i.e., and e.g., either with or without italics. (De-italicize i.e. and e.g. #356)

Request for comments:

1. Decide on nomenclature for anti-abbreviation of HPC. Do we hyphenate high-performance (probably not)? Do we leave it all lowercase?
2. Decide if we want to use the term "login node" throughout? We're definitely logging in to something that functions as a login node, even if it also functions as a head node in some cases.
3. Verify accessibility of colors used in figures versus common colorblindness types.

Edited by @tkphd to separate minor tweaks from weighty issues

[wirawan0]

Commenting on one: "Decide on capitalization rules for headings" -- I would agree with the Carpentries style guide: let's do Title Case Capitalization for all headings. I would mean all levels for headings--not just levels 1 and 2 alone.

[mikerenfro]

Consistent use of "log in to" versus "log into", "log on to", "logon to", "login to"?

Google Ngram and Grammarist lead me toward "log in to" as the correct one for what we're doing (authenticating to get access to a service).

[sunnivin]

Commenting on 1:

According to Oxford Learner's Dictionaries a hyphenation of high-performance seems reasonable.

Personally, I like this writing because it is in accordance with high-performance serving as an adjective.

[mikerenfro]

True, and though Ngram says the hyphenated version is more common, I'm not finding corroborating evidence on a general Google search for "high-performance computing" -- it's a bit over a 2:1 ratio of "high performance" versus "high-performance" on the first page of results.

Even some of the ones using the hyphenated form aren't consistent, and use the non-hyphenated version elsewhere on their pages.

[tkphd]

On the matter of italics vs. boldface for emphasis, I prefer italics for readability. To my eye, bold text draws attention; it is more useful when a reader is expected to scan the document for key clauses. Italicized words & phrases blend into the surrounding text better, producing less eye strain when reading normally. (With bold text, my eye keeps jumping from the part I'm trying to read over to the bold word(s).)

Compare the following example text (source), with keyword in bold:

Emphasis may also be secured by (1) repetition; (2) by the development of important ideas through supplying plenty of detail; (3) by the allotment of more space to the more important ideas; (4) by contrast, which focuses the reader's attention; (5) by selection of details so chosen that subjects related to the main idea are included and irrelevant material excluded; (6) by climactic arrangement; and (7) by mechanical devices such as capitalization, italics, symbols, and different colors of ink."

or with keywords italicized:

Emphasis may also be secured by (1) repetition; (2) by the development of important ideas through supplying plenty of detail; (3) by the allotment of more space to the more important ideas; (4) by contrast, which focuses the reader's attention; (5) by selection of details so chosen that subjects related to the main idea are included and irrelevant material excluded; (6) by climactic arrangement; and (7) by mechanical devices such as capitalization, italics, symbols, and different colors of ink."

[VivaswatS]

These comments pertain to the request for comments from @mikerenfro on Feb 14:
2. As a user and learner, I prefer the term "login node" in the lessons since this is how administrators at my universities have referred to it. This also decreases the cognitive load on the learner by asking them to only remember the one term. +1 for keeping it as is!

3. Using this Toptal Color Blind Filter website, I find that deuteranopia (green-blindness) and protanopia (red-blindness) cause for the red and brown lines (90% and 99% parallel workload) to look the same on the figures in Running a parallel job. A potential color-blind friendly sequential palette could be this, with more options available on the same website.

[longr]

Sometimes we emphasize terms with italics, sometimes with boldface. "The cloud" on 11-hpc-intro is bold, and "The cloud" on 12-cluster is italics. Any significance to the difference? Any preference on just using one?

On the matter of italics vs. boldface for emphasis, I prefer italics for readability. To my eye, bold text draws attention; it is more useful when a reader is expected to scan the document for key clauses. Italicized words & phrases blend into the surrounding text better, producing less eye strain when reading normally. (With bold text, my eye keeps jumping from the part I'm trying to read over to the bold word(s).)

I agree with this (or I did). I have looked through the carpentries style guide and cannot see any information on this. Short of guidance, we have two competing issues here: 1) Bold draws the eyes and I suspect this makes it hard to read for neuro-diverse individuals. 2) At the same time italics should be avoided as it makes the text hard to read, especially for those with dyslexia.

I think the issue actually is not one of whether we should be using bold or italics, it is an issue of why are we using them? I would suggest we do the following:

1. Where we want to highlight a particular concept or make it easier for a learner to find a key concept we use bold (but sparingly - the opening bullets of Why use a Cluster? is, I believe, a case of over use).
2. Italics should not be used as they are hard to read (keep them for mathematical variables but consider replacing those with inline code instead)
3. Any instances of Bold and/or italics where we are wanting to highlight a key term to the learner should be replaced with a link to the glossary and the appropriate entry made. This will allow key terms to be highlighted in a non-intrusive manner, and provide the learner with a quick link to the definition if they are not sure of it.

I am happy to prepare this as a pull request.