Skip to content

Commit f30e642

Browse files
committed
Update links and improve accessibility in Instructor Notes
Some links were outdated, and some link texts went against good practice for accessibility (using the URL or obscure phrases like "this" or "this page"). I have also reworded the point about whitespace differences to make it a bit more logical.
1 parent 6387480 commit f30e642

1 file changed

Lines changed: 15 additions & 18 deletions

File tree

instructors/instructor-notes.md

Lines changed: 15 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Known problems that learners encounter:
1414

1515
## Making a handout
1616

17-
To make a handout for this lesson, adapt/print from [https://librarycarpentry.org/lc-git/reference.html](https://librarycarpentry.org/lc-git/reference.html).
17+
To make a handout for this lesson, adapt/print from the [Reference page](https://librarycarpentry.org/lc-git/reference.html).
1818

1919
***
2020

@@ -54,34 +54,34 @@ working in teams or not, because it is
5454

5555
## Teaching Notes
5656

57-
- Resources for "splitting" your shell so that recent commands remain in view: [https://github.com/rgaiacs/swc-shell-split-window](https://github.com/rgaiacs/swc-shell-split-window).
57+
- Utility for "splitting" your shell so that recent commands remain in view: [Software Carpentry Shell Split Window](https://github.com/UCL-ARC/swc-shell-split-window).
5858

5959
- Make sure the network is working *before* starting this lesson.
6060

6161
- Drawings are particularly useful in this lesson: if you have a whiteboard,
62-
use it to visualise and describe the [GitHub flow](https://guides.github.com/introduction/flow/).
62+
use it to visualise and describe GitHub flow.
63+
The [current documentation of GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow) is text-heavy,
64+
so it might be easier to draw inspiration from the interactive guide "[Understanding the GitHub flow](https://web.archive.org/web/20200728161719/https://guides.github.com/introduction/flow/)" from 2020.
6365

6466
- Version control is usually not the first subject in a workshop,
6567
so get learners to create a GitHub account after the session before.
6668
Remind learners that the username and email they use for GitHub (and setup
6769
during Git configuration) will be viewable to the public by default.
6870
However, there are many reasons why a learner may not want their personal
6971
information viewable, and GitHub has [resources for keeping an email address
70-
private](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address).
72+
private](https://docs.github.com/en/account-and-profile/how-tos/email-preferences/setting-your-commit-email-address).
7173

72-
- If some learners are using Windows, there will inevitably be issues
73-
merging files with different line endings. (Even if everyone's on
74-
some flavor of Unix, different editors may or may not add a
75-
newline to the last line of a file.) Take a moment to explain
76-
these issues, since learners will almost certainly trip over them
77-
again. If learners are running into line ending problems, GitHub
78-
has a [page](https://help.github.com/en/articles/dealing-with-line-endings) that helps with troubleshooting.
74+
- It is likely that learners will run into issues when merging files due to whitespace differences.
75+
For example, a text editor might automatically add a newline to the last line of a file, causing an unexpected difference.
76+
Conflicts can also arise due to Windows using different line endings from other operating systems.
77+
Take a moment to explain these issues, since learners will almost certainly trip over them again.
78+
GitHub provides guidance on [how to configure Git to handle line endings](https://docs.github.com/en/get-started/git-basics/configuring-git-to-handle-line-endings).
7979

80-
- We don't use a Git GUI in these notes because we haven't found one that
80+
- We don't use a Git GUI in this lesson because we haven't found one that
8181
installs easily and runs reliably on the three major operating systems, and
8282
because we want learners to understand what commands are being run. That
8383
said, instructors should demo a GUI on their desktop at some point during
84-
this lesson and point learners at [this page](https://git-scm.com/downloads/guis).
84+
this lesson and point learners at the Git website's [list of available GUIs](https://git-scm.com/tools/guis).
8585

8686
- Instructors should show learners graphical diff/merge tools like
8787
[DiffMerge](https://sourcegear.com/diffmerge/).
@@ -93,9 +93,6 @@ working in teams or not, because it is
9393

9494
- Further resources:
9595

96-
- [git-it](https://github.com/jlord/git-it-electron#git-it-desktop-app) is a self-paced command-line Git demo,
97-
with [git-it-electron](https://github.com/jlord/git-it-electron) its GitHub Desktop successor.
98-
- Try GitHub's [resources to learn Git](https://try.github.io/) or Codeacademy's [Learn Git](https://www.codecademy.com/learn/learn-git).
96+
- [Git-it](https://github.com/jlord/git-it-electron#git-it-desktop-app) is a self-paced Git demo that runs as an app on your computer.
97+
- Try GitHub's [resources to learn Git](https://learn.github.com/) or Codecademy's [Learn Git & GitHub](https://www.codecademy.com/learn/learn-git).
9998
- For instructors, [the Git parable](https://tom.preston-werner.com/2009/05/19/the-git-parable.html) is useful background reading.
100-
101-

0 commit comments

Comments
 (0)