Explicit introduction of stdin, stdout (and maybe stderr)

[katrinabrock]

How could the content be improved?

Current state

From what I can tell, the term "standard output" is first used here:

https://github.com/swcarpentry/shell-novice/blob/main/episodes/04-pipefilter.md?plain=1#L463

but the term is not explained. "Standard input" as a term is first used in the following section, but it's referenced earlier (L95).

"Standard error" from what I can tell is not introduced. I think it would be worthwhile to alert learners to its existence. I remember when I was first learning shell (not through carpentries) being confused why sometimes > or >> didn't seem to redirect my output. The text I wanted to redirect was actually going to std error.

Suggested changes

• Introduce the term "standard input" in or near the section "Why Isn't It Doing Anything?"
• Introduce the term "standard output" in or near the section "Capturing output from commands"
• Introduce the concept (and term) of standard error somewhere. Maybe towards the end of episode 4.

Which part of the content does your suggestion apply to?

https://github.com/swcarpentry/shell-novice/blob/main/episodes/04-pipefilter.md

[somet-code]

Thank you for bringing this to our attention!

I spoke with the other current maintainers of this lesson, and we have the following two recommendations for your first two suggested changes:

• Remove the word "standard" before input and output. For example, on L463, we could change "> is used to redirect standard output to a file." to something like "> is used to redirect output from the terminal to a file.". Similarly, on L483–L486, we could change "Unless told to do otherwise, they read from standard input, do something with what they’ve read, and write to standard output." to something like "Unless told to do otherwise, they read from input, do something with what they’ve read, and write to output." Changes also could be made to L488–L490 to remove the reference to standard.
• Provide brief definitions where these terms are first used. For example, on L463, we could change "> is used to redirect standard output to a file." to something like "> is used to redirect standard output (text printed to the terminal) to a file." Similarly, on L483–L486, we could change "Unless told to do otherwise, they read from standard input, do something with what they’ve read, and write to standard output." to something like "Unless told to do otherwise, they read from standard input (the text you type into the terminal using your keyboard), do something with what they’ve read, and write to standard output (the terminal)."

Given the breadth of information covered in this lesson, we believe discussion of standard error might be best included in the Extra Unix Shell Material lesson in the Incubator. Is there a place in this lesson you think standard error would fit?

Please let us know your thoughts! We also would be happy to have you open a PR.

[katrinabrock]

Thanks for getting back to me. Which of those two options do the maintainers prefer? They seem to be two alternatives that cannot be applied together. Either one seems reasonable to me.

[somet-code]

Yes, these are two alternatives. We didn't have a preference for either when we discussed this issue.

Coming back to this a day later, and considering the novice level of the lesson, I personally would lean slightly toward the first option, to limit introducing new vocabulary and its accompanying cognitive load.

[somet-code]

@katrinabrock Returning to this issue, would you like to open a PR?

[katrinabrock]

I don't have time to devote to it right now, but if no one else gets to it within the next couple months, I'll come back to it.