Post-Teaching Demo feedback

[pawsey-kbuckley]

I'm submitting this "issue list", ahead of one or more PRs, as a result
of recently performing a Software Carpentry Instructor Training Teaching
Demo, during the preperation for the demo of which, I was scrutinisng
the content of "The Unix Shell" lesson quite (some might say too) intently,
and so noticed some things that PRs could address, assuming that the
Lesson and/or Style coveners agree that these things are in neeed of
addressing.

The first is a Styles issue:

• Inability to navigate away from the Setup page back to the Schedule

which I will have commited ot the Styles repo.

The remainder are specific to "The Unix Shell"

• Introducing the Shell: Background

The phrase "At a high level, computers do four things" doesn't tell
the full story.

Not all computers "Store data" nor "Interact with us".

Some computers will stream data in and out, and merely "run programs"
on the data stream.

I'd like to suggest that, in the context of "Software Carpentry" and in
a "researcher-focussed context, that the phrase be changed to:

"At a high level, computers that run software to process user-supplied
data, do most, if not all, of the following four things:"

• Input and Output boxes

There are a couple of places where the seperation of Input and Output
boxes, or rather the theme that a command that provides output, as
opposed to returing to a prompt, breaks down.

In the "Navigating Files and Directories" episode, we use a standalone
"Input" box to show the command "we will dissect into its component
parts", however, when we provide the command and its Output, the two
are combined into one box, thereby breaking the "Input and Output"
theme.

Perhaps that could be re-rendered as

Putting all that together, our command above

[ ls -F / ]  (the input box)

[ Applications/         System/    ]
[ Library/              Users/     ]    Output box
[ Network/              Volumes/   ]

has given us a listing of files and directories in the root directory /.

Note that we would drop the "An example of the output ..." sentence
as the presence of the Output box fits in with what the student
expects.

In the "Pipes and Filters" episode, we use the example of a "wc -l"
without any arguments to talk about the shell as "it just sits there
and waits for us to give it some data interactively."

I think this would benefit from an explict empty line after the
prompt and command line.

So, we would have

What happens if a command is supposed to process a file, but we don’t
give it a filename?

[ $ wc -l         ]
[                 ]

Notice that the shell has accepted our command but has not produced
any output, and instead presented us with an empty line.

Since it doesn’t have any filenames, wc assumes it is ...

This presentation, I suggest, links into the idea of the shell presenting
us with a new line, albeit denoted by the right-arrow, for data-entry,
that is encountered in the Loops episode that comes next.

• Layout of text in Output boxes

One of the things I picked up on, whilst reading through the lesson
as a whole, was that the amount of space taken up with the Output
boxes for file and directory listings varies (no pun intended) widely.

The output from the very first command in "Introducing the Shell"
shows eight directories, laid out as follows

[ Desktop     Downloads   Movies      Pictures   ]
[ Documents   Library     Music       Public     ]

however, on a standard 80x24 terminal, those names would be
presented on one line, this

[ Desktop  Documents  Downloads  Library  Movies  Music  Pictures  Public ]

Interestingly, in the next episode, "Navigating Files and Directories"

the display of a directory containing the eight directories above, plus
an "Applications" directory, produces what the episode displays, vis:

[ Applications  Documents  Library  Music     Public  ]
[ Desktop       Downloads  Movies   Pictures          ]

but then later on in the same episode we see

[ $ ls -F /
[ Applications/         System/      ]
[ Library/              Users/       ]
[ Network/              Volumes/     ]

as opposed to what a standard terminal would display, vis

[ $ ls -F /
[ Applications/  Library/  Network/  System/  Users/  Volumes/    ]

One example, of where a previous listing of directory contents is
presented in a different way in a later episode would be in the
"Working With Files and Directories" episode, after the "ls -F"
where the listing of the same set of files that were presented,
correctly, in the previous episode, as

[ creatures  molecules           notes.txt  solar.pdf     ]
[ data       north-pacific-gyre  pizza.cfg  writing       ]

is now, with the addition of the newly created "thesis" directory,
presented as a single line (this may wrap in the submission!)

[ creatures/  data/  molecules/  north-pacific-gyre/  notes.txt  pizza.cfg  solar.pdf  thesis/  writing/    ]

some 102 characters wide which is not what the students would see
on the tutors terminal.

There are other examples of this, though I am sure that, as the lesson
contents change, the content of output boxes may well do so too, which
may explain some of the inconsistencies currently seen, however, I feel
it would be useful to stick to one terminal width for rendering output,
not least at the tutor will rarely alter the terminal width, once they
have arrived at a font-size that satisfies the viewing needs of the
class.

As I say, I am happy to create and submit PRs for some, or all,
of the issues, but thought to flag the issues up first, in case other
points of view are held.

Kevin

[pawsey-kbuckley]

Apologies for the multiple edits in the above: ironically, I omitted the boxed text
Markdown formatting when presenting my representation of the boxed text
in question.

[gcapes]

Hi @pawsey-kbuckley
Thanks for the issue!

You've raised a number of points here which would be easier to discuss as separate issues. Could you please create a new issue for each topic, and close this issue?

[pawsey-kbuckley]

As you will see from the above, I have created the separate issues.