Navigation Menu

Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

2021-02 review of lesson text, general notes #297

Open
6 of 9 tasks
mikerenfro opened this issue Feb 15, 2021 · 7 comments
Open
6 of 9 tasks

2021-02 review of lesson text, general notes #297

mikerenfro opened this issue Feb 15, 2021 · 7 comments

Comments

@mikerenfro
Copy link
Contributor

mikerenfro commented Feb 15, 2021

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)
  • 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

@mikerenfro mikerenfro added the coordination Agenda item for Coordination Meeting label Feb 15, 2021
@mikerenfro mikerenfro changed the title 2020-02 review of lesson text, general notes 2021-02 review of lesson text, general notes Feb 15, 2021
@tkphd tkphd added good first issue help wanted and removed coordination Agenda item for Coordination Meeting labels Apr 16, 2021
@wirawan0
Copy link

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
Copy link
Contributor Author

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
Copy link

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
Copy link
Contributor Author

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
Copy link
Collaborator

tkphd commented May 24, 2021

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
Copy link

VivaswatS commented Jun 16, 2021

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!

  1. 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
Copy link

longr commented Jul 8, 2021

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

6 participants