dhri-curriculum / command-line Goto Github PK

On "command-line/sections/grep.md" I think we need to explain a little bit about what grep is and how it's a different command from cat. I'm not sure that's entirely intuitive to the reader. I would suggest walking through the pipeline explaining what each step does.

On the command-line/sections/pipes.md page the -w flag is introduced, but there's no explanation of what a "flag" is. Do we want to use the word "flag" here or would it be easier to describe it as an option?

Some of the lessons were written by Jojo and use her username as an example. I think it makes sense to keep that as is, unless someone thinks it would be confusing for the institute participants if I come up as workshop leader and Jojo's name appears throughout the lessons?

Send to Kalle (via Slack):

1. A headshot—make sure it is recent and as high-resolution as possible (if you have questions, feel free to reach out!).

2. A bio—max 150 words.

3. Any number of links to current websites and projects you have worked on and want to display.

4. A "Meet your instructor" blurb (keep it short, less than 200 words) about why you got involved/how you have had use of the tool(s) that are introduced in your workshop.

   For this part, think about how you build trust and report with participants in digital research institute. Since we cannot build that if we don't meet participants in-person, how would you come up with language (narrative/rhetorical strategies) to provide a surrogate for this face-to-face interaction?

• Make sure you are in the right branch and have recently pulled all the content from the GitHub repository before you start working.

• Create a theory-to-practice.md file in your repository
  Here, you can find the template for theory-to-practice.md. Copy the contents into a new file in your repository.

• Add suggested further readings (optional)

  • Use ## Suggested Further Readings to indicate the beginning of the section, and bullet points for each of the sources (in markdown, you use - on a new line to create a bullet point).

  • If the reading has a DOI number, make sure to add it. If it does, you do not need to add any additional bibliographic information.

• Add other tutorials (optional)
  Use ## Other Tutorials to indicate the beginning of the section, and bullet points for each of the sources (in markdown, you use - on a new line to create a bullet point).

• Add projects or challenges to try (optional)
  Use ## Projects/Challenges To Try to indicate the beginning of the section, and bullet points for each of the projects/challenges (in markdown, you use - on a new line to create a bullet point).

• Add discussion questions (optional)
  Use ## Discussion Questions to indicate the beginning of the section, and bullet points for each of the questions (in markdown, you use - on a new line to create a bullet point).

• Make sure you are in the right branch and have recently pulled all the content from the GitHub repository before you start working.

• Create a frontmatter.md file in your repository
  Here, you can find the template for frontmatter.md. Copy the contents into a new file in your repository.

• Finish the Abstract section
  Transfer over relevant portions from readme.md into the ## Abstract section in the frontmatter.md file.

• Finish the Learning Objectives section
  Transfer over relevant portions from readme.md into the ## Learning Objectives section in the frontmatter.md file.

• Check this one for free: the Estimated Time section
  Leave the ## Estimated Time section in the frontmatter.md file as it is (we will come back to this during our testing period).

• Finish the Prerequisites section
  Think of prerequisites that will be important for learners to know in advance of this workshop that should go into the ## Prerequisites section in the frontmatter.md file.

• Finish the Pre-reading suggestions section
  Think of/search for reading suggestions that could be good for learners to have read in advance of this workshop that should go into the ### Pre-reading suggestions section in the frontmatter.md file.

• Finish the Projects that use these skills section
  Think of/search for projects that you know, which could be good for learners to look at in advance of this workshop that should go into the ### Projects that use these skills section in the frontmatter.md file.

• Finish the Ethical Considerations section
  Think of ethical quandaries that could be good for learners to consider in advance of this workshop that should go into the ### Ethical Considerations section in the frontmatter.md file.

• Finish the Resources section
  List any required installations, shortcut sheets, or other resources that can be helpful for learners to take care of/look at in advance of this workshop and add them into the ### Resources (optional) section in the frontmatter.md file.

• Finish the Acknowledgements section
  List all the full names of every person who have worked on and contributed to this repository over the years in the ## Acknowledgements section in the frontmatter.md file. Each person should be added as a bullet point list.

If you have one, a link would be cool here.

You can change the color of your Terminal or BashShell background and text by selecting Shell from the top menu bar, then selecting from the menu under New Window.

Error in ingestion for django-app? Or is it something else?

@smorello87 - I'll look at it but wanted to tag you too.

Should we have challenges even for the introductory sections of our workshop (e.g., in the Command Line lessons.md "What Is the Command Line?," "Text Editors," and "Why is the command line useful?")?

In Sprint 2, once again, we need your help moving content over from the old format into a new format. This time around we will do so in two steps:

1. Copy-paste of content
   It doesn't sound very fun but it will be rewarding to go over the material once again and review the flow from one lesson to another.

   • Create a file lessons.md in the root of your repository. This will be the home of the entire lesson-flow.

   • For each of the lessons in the sections directory in your repository:

     • Remove any lines that contain "navigation bars" (eg. <<< Previous Next >>>)
     • Ensure that the first header is of level 1 (# ) and any following headers are level 2 (## ), and if there are nested headers under that, that they are consequential with the previous ones.
     • Once you've done that, copy the text from the section file, and
     • Paste the contents after the end of the lessons.md file.

2. Once you have the whole flow set up in the lessons.md file, it is time to begin looking over the style and content of the entire body of the workshop:

   • Ensure that any multi-line code blocks are correctly encased in three after one another—```— feel free to also annotate whether the code is python, html, css or anything else by adding those terms after the triple backticks. (You can read more about this technique here)

     ` ` `css
     testing out code
     ` ` `

     (In this example I have used spaces between the backticks because otherwise the block would not render correctly here, so keep the backticks with no spaces in your real-world work.)

   • Inline code, commands, filenames, or keyboard shortcuts should also be surrounded by single backticks:

     As you can see above, the `=` sign lets you assign symbols like `x` and `y` to data.

     (This example comes from the python workshop. You can see it in action here)

   • Feel free to use bolding (**bolded**) and italicizing (_italicized_) where you see fit, but sparingly. If it clarifies your content, good. Just remember that they can be overwhelming.

   • Try to make sure each section ends with a question/challenge/problem that makes our learners act and think on their own. Here's how the formatting should look (keep the ## Challenge header even if yours isn't technically a "challenge"):

     ## Challenge
     
     Here is where I write the challenge as a regular paragraph.
     
     ## Solution
     
     Here is where I write the solution as a regular paragraph.
     
     ` ` `python
     print("In the challenge and/or the solution, you can, of course, use code blocks and styling too!")
     ` ` `

   You can see an example in the python workshop, and you can see what it will look like in production—albeit still very much under development at the end of this page.

   • Pay attention to images that are, or should be, present. Do you need more/newer screenshots? Are the existing ones too old, of a low resolution, blurry, unclear? Please provide (i.e. upload screenshots with clear names) in an images directory that you can create in the repository's root directory. Link them in your lessons.md file by using markdown:

     ![don't forget to describe your image for the alt text here](images/your-image-name.png)

   • As above, pay attention to where you think an animated gif or a screencast might be appropriate, and make a note of it in the text. You can either put a placeholder, or a comment using inline html comments:

     <!-- it would be good with a screencast/gif here -->

   • If you find images that have been borrowed from elsewhere and credits are missing, please try to make sure we have appropriate credits in the text inline, or immediately after the image. (Pro-tip: You can use Google image search to find sources for most files.)

Resources

Style example

lessons.md example from project-lab

At this point, the lessons.md file should be complete enough that you will be able to go through each lesson and come up with (at least) one evaluative question per lesson, on what the learner should have picked up from the lesson. They should be expressed in the form of multiple-choice questions, with one or more correct answers.

How to add a multiple-choice question

Go through the lessons.md file, and for each lesson, create a new section at the end (## Evaluation) where you will add the question and each of the answers, marking the correct ones with a * at the end of it. (See an example here.)

Optional: Add open-ended questions

If you want to, in addition to the multiple-choice evaluative question, you can also raise an open-ended question, expressed as “Do you think you can answer this question:” As there is no easy way to programmatically understand the input in a text field to such a question (although, of course, not impossible), we will not be able to build such a functionality into the website. But we can offer open-ended questions as a feature for the learners to think further about the workshop’s contents. Perhaps they can be about an ethical aspect of the lesson?

• Go through lessons.md (and other files) and find all important terms in need of definition to help learners grasp concepts, tools, commands, etc. List the files in a text file, or keep them in this issue feed below, for instance.

• Add a file to the glossary repository's terms folder called <term>.md for each of the terms.

  • How do I add terms to the glossary? <— See instructions

I copy/pasted questions from previous DRI/DHRI exit slips, but not sure if that's the kind of formatting you wanted us to use!

I appreciate the framing and orientation you've taken for this workshop! Just a couple of things I have in mind that may be useful.

Abstract
The opening sentence "By this point in our academic careers, most of us have figured out some ways we like to interact with computers" can sound a little intimidating to someone who is very nervous about/around computers/tech, especially since this will be the first thing they read in one of the very first workshops they take. This is especially so because tone is hard to gauge in writing. Perhaps something more inviting that remind folx that they have already been interacting with their computers can be useful?

Ethical Considerations
I think Wendy Chun's writing is really great here! Maybe a little elaboration of what the quote, especially the sentence "The command line is a mere operating system (OS) simulation" can be helpful for understanding?

Looks like I made a mistake back in the day when designing the challenges in this lesson. @arojas1 in Software Design Lab noticed the odd behavior. Making an issue here for posterity but will follow up with a PR to resolve the issue.

Patrick Smyth had created a number of screencasting GIFs for the Command Line workshop. Do you think it's a good idea to keep them on the lessons.md file? If so, in what sections should they live? Right before the Challenges, perhaps?

If you have one, a link would be cool here.

On the command-line/sections/pipes.md page the -w flag is introduced, but there's no explanation of what a "flag" is. Do we want to use the word "flag" here or would it be easier to describe it as an option?

Left TBD from sprint 1, see #53.

Hi Jojo... things seem to be coming together very nicely for this lesson! It looks as though the first page is missing a "learning objectives" section which should be included in all the lessons. I think Patrick was working on adding this to the style guide. Generally learning objectives appear early in the lesson and read something like:

During this lesson students will:

• become comfortable navigating through their directory structures using...
• create a file using "touch"

Etc.
Let me know if that's not clear or if I've just missed this section. Thanks!

Hi, it's me again, looks like some bits and pieces of mark up are getting rendered as a header for no apparent reason. Here's an example:

At the end of the lesson, it would be very helpful for students to have suggestions about what could and should come next if they want to learn more about the command line. What are some commands they could look up? What tutorials could they also use that will help them to become more confident? How would you suggest they practice what they've learned?

Here's a good place to connect to the Zotero library and explain what materials are there and how they could be useful.

People always ask about grep and regex. Should write something small or link to a decent resource.

Going through the notes that I have from January and the introduction to the command line lesson, I think I found a few other terms that need definition:

• command
• argument
• prompt
• syntax
• pipeline
• options
• flag

• Look at your workshop on the website to see what your workshop currently looks like, and what looks like it needs to change.
• Think about order and transitions—do the lessons follow a logical pattern and is it working? Do you need to add something somewhere? Are the transitions between the lessons clear?
• Can you add a challenge at the end of the lesson that summarizes what the learner has learned, and activates the knowledge in an interactive way.
• Think about the length of the lessons — are they too long? Too short? In general, each lesson should cover one topic, or one particular skill — or perhaps connect two skills. If you find that you’re covering more than that in one lesson, perhaps they should be split into more than one.
• While reviewing the lessons.md file, think about vocabulary terms that we should add in an easily accessible "dictionary" for our learners.

Feel free to reach out to me and @lmrhody and ask for help, if you need it. Also feel free to involve others in the group!

Feel free to close this issue after you have pushed all of your local branch updates to your GitHub repo, so I can initiate a pull request to the v2.0 branch. (If you feel comfortable and interested in doing it yourself, you can do that as well, of course!)

This is the issue that closes out the v2.0 edits from you. Thank you so very much for all your hard work this summer!

lessons.md

• Accept any pending pull requests

• Implement all the edits/requests that you have left from your colleagues.

• Add any additional content you think is needed for version 2.0 _and open any other using the label in your repo

• Ensure the length of each lesson is not too long
  each section (beginning with a level 1 heading [#]) should be no more than 3-4 paragraphs

• Ensure temporal references and references to other workshops are removed (since learners will “attend” these workshops mostly asynchronously)

frontmatter.md

• Finalize and streamline all sections

• Ensure your abstract is no longer than ~100 words
  If you need/want them to be longer, you can create a new first section in lessons.md and put the longer version of the abstract there.

• Resolve any "TBD" content.

• Make sure collaborator lists are complete with roles and links
  see Di’s example but feel free to add links to people’s websites!

• Ensure all Projects and Readings have "annotations"
  annotations = 1-2 sentences answering “Why is it important for our learners to read or expose themselves to these readings/projects”? For examples, see agenda doc

theory-to-practice.md

• Finalize and streamline all sections

• Resolve any "TBD" content.

• Ensure all Projects, Readings, and Tutorials have "annotations"
  annotations = 1-2 sentences answering “Why is it important for our learners to read or expose themselves to these readings/projects”? For examples, see agenda doc

Any thoughts on how to fill out these sections for the Command Line workshop?

https://code.visualstudio.com/docs/setup/mac

1. Should we add it to the installation page?
2. Need to ask someone with a PC if this is also needed on Git Bash

The Neal Stephenson link is broken. It looks like the original host removed the file from their website. The only free version with the entire essay I found has commentary interspersed, but it’s not too bad:
http://garote.bdmonkeys.net/commandline/index.html

In command-line/sections/text-editors.md, there is a lot of description of what MSWord text looks like, but not as much about what plaintext actually is. Consider revising to read: "Plaintext files are exactly like they sound--text without any formatting, such as color, text size, and font type. Plaintext files can be opened and read read from the command line, as well as with editors like Notepad."

Also, you could also introduce text with XML encoding (ie. like from Word) as "rich text" files to help clarify the difference.

We may also want to point out that commands are typically words, that some commands have options that help you to clarify your command so that the computer can respond more specifically. That options often follow a single dash if they're letters. (For example ls -LP is a command and an option. The command is to list the items in the current directory (or folder), and -LP says to list all the details. The next step is that you can take the command and the options, and you can put them someplace using a symbol... etc.... ls -LP > contents.txt Now if you open up the contents.txt file, you can see that you gave the computer a command "list files in the current directory" you were specific in your request "list them in long form with properties" then you told the computer to put the results in a new txt file called contents.txt. If you open the contents.txt file in a text editor like VSCode, you can see everything that is in your directory with the properties associated with them.)

I think this kind of information, about how the command line understands your input if it follows a specific pattern could go well on the why-is-the-command-line-useful page.

Both README and first section

We want to make sure that the theory-to-practice.md file is somewhat more useful welcoming than only a couple of bulletpoints, so this feature request concerns the end of your workshop.

Imagine the theory-to-practice.md file as a form of mentoring and consultation (or a step in that direction): What would you say at the end of your workshop to help think about how the skill the just learned could be refined and improved? Can you give the learner something more to go on than a bulleted list? Something that would entice them to stay on this page and choose to dig deeper into the skills/tools in your workshop?

Concrete step

Add one or more regular paragraph/s at the top of your theory-to-practice.md file (under the line that contains # Theory to Practice and before ## Suggested Further Readings). If you need, use formatting (** for bolding and _ for italics), and/or headings (but make sure to only use level 3 headings—###).

You can see an example here. If you have any questions, don't hesitate to tag @kallewesterling and comment below, or DM via Slack.

This is what I get when I try and preview the content of the lessons.md file on Kalle's portal

This is the broken URL: https://kallewesterling.pythonanywhere.com/preview/command-line/lessons/sections/images/worddoc.png

to get to their regular files in MinGW, the path is

/c/Users/<their username>/etc

I would say the command line requires a greater visual grasp of the relationship between directories that most of us are used to using. I suppose that is what come of the Graphic User Interface we are know from windows applications. Point-and-click is great for navigating quickly, but it doesn't leave you with much real understanding of what the program is doing behind the scenes. Which is reason enough to explore the command line.

Perhaps we should start by exploring the GUI way of navigating your hard drive/folder structure and then move into the command line.

Heya, I just have some suggestions to improve the clarity for the lessons that may be helpful to you. :)

What does "text-based" means?
I think there can be a little clarification between what you mean by 'text' and word processed here. The sentence that seems to be the bulk of the explanation seems a little dense (quoted below); maybe breaking it up can be helpful?

As we start to get comfortable typing commands to the computer, it's important to distinguish "text" from word processed, desktop publishing (think Microsoft Word or Google Docs) in which we use software that displays what we want to produce without showing us the code the computer is reading to render the formatting. 

Plain text
The comparison to rich text before the explanation at the end of the subsection may cause some confusion. Since it is not directly related to the quote, maybe the comparison can be removed until you introduced what rich text is?

Getting to the Command Line: macOS
Perhaps a series of screenshot/gif/screencast (like the later solutions) can be helpful to demonstrate what the navigation looks like, just in case folx are not familiar with the magnifying glass.

I'm also not sure why You can change the color of your Terminal or BashShell background and text by selecting Shell from the top menu bar, then selecting a theme from the menu under New Window. is in italics here. I didn't make any edits just in case it's intentional, but in case it isn't, here it is~!

Getting to the Command Line: Windows
Is there a resource you could link folx to for the reason why we won't use their terminal?

Also the keyboard shortcuts to navigate to gitbash for windows is: Win (⊞ ) > type gitbash>Enter.

Command prompt
I think having all of the command prompt discussion in this section will useful. The additional explanation in the macOS section can be brought in here instead.

Creating a file
Could you add a description to what the touch command does? You've done so for all the other commands so far.

A note on file naming
You mentioned "report to class" here for the activity of creating a file with spaces, what could an alternative to class be in this case?

When you're suggesting how to name files, maybe you can also mention that it will be useful to avoid periods in file names too as they sometimes can be confused with system files or file extensions.

Creating a cheatsheet: Challenge

It may be good to remind folx what code does in the terminal. It was briefly mentioned in the installation guide for when folx were adding the program to path so that they can open it from the terminal (and is also the program name, so we are calling this program to open this file). This will also keep it consistent with the descriptions of commands that you've been using throughout the lesson.

Pipes
It may be useful to describe/explain what a flag is. You mentioned it in the section on cleaning the data, but perhaps the description can be brought forward since it is first referenced here?

Note: Clearing text
The keyboard shortcut is CTRL + L for windows.

Searching text data
A little more context to regular expression can be helpful. For example, what do you mean by infamously human illegible commands?

Formatting
I think that there can be consistency in how you're quoting functions/keys/files, you switched between ` and " through the workshop (like me in mine. >.<).

You've also provided keyboard shortcuts to some but not all, maybe it will be useful to do it for all?

Sorry it's so late. The suggestions are really for minor edits so I don't think they will eat too much into your next sprint? >.<

Content

• adapt content to fit with macOS Catalina's use of zsh
• section 11 (Interlude) needs images and an example of how tab completion works
• clear screen in Windows Bash info needs to be added

Delivery

• consider pacing and how to deliver info

Should be

cat nypl_items.csv | uniq > new_nypl_items.csv

Instead of

cat nypl_items.csv | uniq -d > new_nypl_items.csv

• Typo in section Text Editors: in the line below the visual of the word doc opened in a text editor, commandline should be two words.
• Make sure to be consistent when using etc. (make a decision to use the period or not, right now you are jumping between the two)
• For downloading Gitbash instructions, change step 2 to be on a new line.
• In spelling tips, maybe change "your spelling will be the first thing you check" to "your spelling should be the first thing you check". Just a suggestion; does not need to be implemented
• In the 'Navigation" section, you define pwd, but do not define cd ("change directory") or list ("list"). It would be helpful, I think, to include those definitions.
• In 'Creating files and folders', might be useful to remind that mkdir stands for "make directory"
• In "Exploring Text Files", it might be useful to define what the "less" command means. I wasn't familiar with the term paginated, but maybe others will. Just a suggestion; does not need to be implemented.

Other than these small thing, I think your workshop looks really great! It's very clear to me and I think it will be very well received.

Is there an explicit place where we can connect the lesson and why working from the command line (at least knowing how to do it even if you don't want to do it all the time) is important for a humanities scholar who's interested in digital projects.

I can imagine connecting this to Stephen Ramsay's blog post "Life on the Command Line," which I'm trying to find a copy of since his site seems to be down at the moment.

For example, it's hard to install your own version of Omeka or even WordPress if you don't know how to interact with the command line. You'll need to learn how to use the commands if you'd like to ssh into a host... and that might be important if you want to work with files that are on another computer.

• Make sure you are in the right branch and have recently pulled all the content from the GitHub repository before you start working.

• Create a assessment.md file in the root directory of your repository
  Here, you can find the template for assessment.md. Copy the contents into the new file in your repository.

• Complete the quantitative self-assessment section

  • Use ## Quantitative Self-Assessment to indicate the beginning of the section.

  • Move all the relevant quantitative self-assessment questions from DHRI/DRI exit slips found in the GCDI Google Drive over to this file.

  • Each question should be a regular paragraph.

  • Each question should have multiple choice answers, added as bullet points under the paragraph (in markdown, you use - on a new line to create a bullet point).

  • Make sure that the questions enable the learner to evaluate their understanding of specific concepts from the workshop.

• Complete the qualitative self-assessment section

  • Use ## Qualitative Self-Assessment to indicate the beginning of the section.

  • Move all the relevant qualitative self-assessment questions from DHRI/DRI exit slips found in the GCDI Google Drive over to this file.

  • Each question should be a regular paragraph.

  • For each question, think of readings/tutorials/projects/challenges from the "Theory to Practice" section to direct them to, and add a note of that as a bullet point under relevant questions (in markdown, you use - on a new line to create a bullet point).

  • Make sure that the questions enable the learner to evaluate their understanding of specific concepts from the workshop.

Hi all!
Unsure what to do with this section, as it mentions the workshops that have been historically taught after the command-line one. If you anticipate the DHRI is going to follow the same structure as in the past, and will be building up on the command-line as well, I can leave as is, otherwise, we should return to it once we have a better understanding of the larger picture?

At the end of the lesson, how can you directly and explicitly connect the lessons they've learned in this lesson with what is coming next? For example, how does it help with learning git? How does it help with HTML/CSS or GIS or other courses along the way.

What are the most salient take aways from the lesson?

This is a good time to also do a quick review:

When we started, we reviewed what the difference was between a .txt and a .rtf file was. We learned that text editors that we want to use are a kind of software that doesn't allow for formatting of font, like color and size. Text editors are a different piece of software than Bash, which is a text-based shell that allows you to interact directly with your operating system giving direct input and receiving output. We learned commands that help you navigate your computer's file system.... (etc. etc.)

Thanks!