Remove text editor command lines from main lesson text

[fherreazcue]

I believe most of the course is self sustained in the sense that you could be using any os and follow it without issues, but references to setting up the core editor and instructions on how to write text to the files from the terminal make it confusing for a first timer, particularly if they come from an os where terminal editors are not standard. Several issues have been raised relating to the text editors (see for example #709, #743, #847), but I believe the added info should actually be more of an appendix (like the reference to "Which Editor"), only referred to in an instructive example when doing a commit without -m, as it is actually one of the very few scenarios where it would be relevant.

In particular, I think Chapter 2 (Setting Up Git) is completely overwhelmed by editor info, when it is actually an unnecessary step, but most importantly, Chapter 4 (Tracking Changes) 'mixes' git and nano commands, which makes it hard for a new user to disentangle them. Creating a text file and adding or modifying text in that file is something any computer user can do without receiving command line instructions on how to, and it actually makes it much more relatable to real work, where a user can modify files without even remembering git exists. I believe it would be much simpler and intuitive to remove all the nano and cat commands, and simply refer to the content of the file.

[kekoziar]

My experience with teaching hands-on workshops is, learners are more likely to follow along if they are able to execute the same commands as the instructor. That is why a fundamental element of The Carpentries lessons are example code chunks. Removing from the lesson the nano commands will create confusion, and remove the uniformity that the Carpentries provide - we're no longer teaching the same tools in the same way.

Staying on the command line during the lesson reduces cognitive load load for the learners. In the past, I've attended (non carpentries) workshops where I didn't really learn anything because the instructor was editing their files using a method that wasn't explained. They were quickly going between different windows on their computer. Even when I realized their editor was completely separate from the tool the workshop was supposed to be about, I couldn't follow along because their set-up for interacting with their editor was different than on my computer. I ended up just watching, and not really learning anything. Using nano (as setup for the workshop) ensures everyone's environment is the same.

While this lesson can be used by an individual as a self-paced tutorial, please remember it is a lesson taught in a workshop, usually after the Shell lesson. Certified carpentries instructors understand this placement, and those who wish to teach it stand-alone, understand to expand on using nano from the command line when they first encounter it. In most git workshops I've attended (instructor or helper), the instructor usually will refer to the editor list as, "We're going to use nano for the lesson, but for those who want to change their editor after the workshop, there a list of config commands in the lesson. I'm happy to help set up text editors during the break."

That said, if you think The Carpentries should adopt a different editor for both the Shell and Git lessons, I'm happy to pass along info supporting that to the Shell maintainers (but chances are, they also will want to keep the lesson contained to only working from the command line).

[fherreazcue]

There is a big difference between being able to "follow along" and understanding what is being done. I believe the cognitive load is not reduced by staying on the same window, but rather by making it clear which actions are relevant to the new tool (git), and limiting the simultaneous exposure to unfamiliar tools (like nano). With the current setup, I believe that the average novice user will not distinguish nano from git, and it will seem to them that they are bound to each other.

In fact, the example that you gave (of an instructor using an unexplained tool to edit a file) precisely adds to my point. Nano is not a tool that is explained in this course, and "staying in the same window" will not reduce the confusion, it will add to it. Your experience was that of a poorly prepared lesson, in which the instructor did not set up an appropriate environment to show the changes that were being made, but (at least for the git lesson) this is easily fixed by simultaneously showing the terminal and the text editor. This actually further contributes visually to the separation of the git commands being used (in terminal), and the file editing (in a separate window).

How I tend to teach this bit of the lesson is by also showing the "planets" directory, so that added files are being tracked not only on terminal, but they can be seen at all times in the screen. (see screenshot).

The "Certified carpentries instructors" that start this section using a phrase like "We're going to use nano for the lesson..." unfortunately seem to be suffering from an expert bias. They are assuming that their pupils will be able to understand and separate all nano commands from those of git, when they will likely just follow along, unless they have experience using command line text editors, which is actually rarely the case in novice users.

Finally, my point is precisely that the editor should not matter, so no, I am not trying to suggest a different editor. The very suggestion of this issue is that the file editing should be taken away from the terminal, so that their commands are not intertwined with git's.

[martinosorb]

I agree with @fherreazcue. I always find myself having to show them that what I'm doing is really just editing text, and there's nothing special with nano specifically. And that you could do the same in any other way you like. His arguments are quite compelling - it's good to separate git from everything else we do, to show that git can apply to a variety of circumstances.

[kekoziar]

I am remembering many times during workshops when someone is using a different text editor, then suddenly they have a problem with the editor that no one in the workshop can assist with, because no one has experience with that particular editor. We lose time and effort during the lesson.

I will always stand on having the experience be as similar as possible for all learners. It's why the lessons revolve around a singular fictitious research scenario, instead of everyone bringing their own data to work through. It's easy enough to say that we're all using nano for the next few hours, and set it up, then refer the learners to the page that has the config commands so they can update to their favorite text editor afterwards.

Re using the cat command: the purpose isn't to get practice using it, but to echo out the changes we just made to the now closed file so learners can see the contents and type along (often without feeling like they're singled out for asking the instructor to slow down).

[kekoziar]

How I tend to teach this bit of the lesson is by also showing the "planets" directory, so that added files are being tracked not only on terminal, but they can be seen at all times in the screen. (see screenshot).

I'm actually surprised that your learners can read that. If they can, great. But, we shouldn't assume folks have two monitors at home, a ton of space with a single monitor to see this, or that instructors have equipment beyond a large screen monitor.