DamienIrving
commented
3 years ago Related to this task: The introductory text in "Building Tools with the Unix Shell" is a little messed up after the transition from two bash chapters to three. For instance, it talks about scripts, which aren't introduced now until the following chapter.
gvwilson
We need to read through the first sentence of each chapter section and chapter introduction and make sure that, for the most part, there is a clear "topic sentence" introducing the topic at hand and why we care about it (not necessarily the first sentence, but should happen sometimes before the second or third paragraph).
Notes from the reviewer (@ChristinaLK):
Good examples
Introduction to chapter 3 (Going Further with the Unix Shell): "This chapter extends these ideas to show how we can create new tools by saving commands in files and how to use a more powerful version of wildcards to extract data from files."
Section 3.2, using variables in a script: "Getting the name of the author for only one of the books isn't all that useful. What we really want is a way to get the name of the author from any of our files." (and then go on to talk about variables)
Examples that could be improved
Section 2.1, starting to use the shell: I'm looking for something like "Our first shell commands will allow us to navigate and view the contents of our file system, a foundational skill for using the shell to run other commands and use files organized in a project."
Section 3.6, introducing shell variables: I'm missing the final "so what"---like "knowing about shell variables allows us to customize our shell working environment if we use it frequently."
If you only review one chapter for these "topic sentences" I would recommend chapter 7. The content in that chapter is crucially important, and currently can read as somewhat unconnected topics around people and project management. A topic sentence in each section that links back to the goal of empowering people to collaborate together and in a safe and productive manner (or connecting a particular section to a previous section in the chapter, e.g. 7.6 is really a follow on from 7.5) would go a long way towards helping that material cohere. That, or adding more details to the introduction, outlining the major topics that will be covered in the chapter.