git-novice
git-novice copied to clipboard
swcarpentry
Should we change the story behind the lesson?
We periodically get concerns about the story behind the lesson (Wolfman and Dracula research planets), the most recent is discussed in this thread. I'd say the more frequent complains are the story being a bit "childish", in the sense of not serious enough of a scientific setting, or disconnected from the rest of the workshop, in the sense that the story uses .txt files instead of "code".
I'd like to open a discussion on whether we should change the story or not.
Some points I think are worth to mention:
- I think the lesson should not have any coding involved. This reduces greatly the cognitive load of the lesson, allows to alter the order of the topics in the workshop, and is agnostic about programming languages, so I'd prefer to work only with
.txtfiles; - typing is hard, specially if you are trying to understand how Git works at the same time, so the least typing the better;
- no extra tools (other than Git and a text editor) should be required: it's already hard enough to get all Git installations working in a workshop;
- having a closed, non-personal story is really important: learners should be focus in learning Git and not spending time on writing prose or code. I think that stories with open tasks, such as "write a brief bio about yourself" or "let's add a file with some comments about our favorite movie", are distracting and hard to complete by some people.
I think there's value to having something "childish" in the curriculum. git is hard for a lot of people to learn and figure out, but in the end, they can see the utility. I recently saw someone try to teach git by using the evolution of R or bash scripts and it was really hard on the learners. They had just learned bash/R and it felt like piling on. I'm pretty sure that installing Jekyll and dealing with ruby etc would cause similar problems. If the planets are too childish then I wonder about perhaps having people put a to do list under version control. They can see this as a bit of a diary where they can go back and forth through time, perhaps think about how they could merge their to do list with what their advisor wants them to do, etc.
I get some snickering every time I teach the lesson, but nothing more than that, and I don't think any of the critique stickies have complained about it. I did get one learner recently who wanted to see git applied to a simple scientific code, but I agree that the cognitive load on that is high.
I've seen a few alternative examples using the structure of the SWC content, such as @BillMills doing one where learners created a thesis repo and edited abstract, methods, and results chapters. Otherwise, it worked just like any other SWC lesson I've helped with and the focus was on git. Although similar to the to do list, it highlighted more how it could be used by researchers (e.g., documents in LaTeX).
I think the planets example is ok, it doesn't require background info and keeps the focus on git rather than the documents. It also lightens the mood, I got a few laughs going off-script and putting pluto.txt into .gitignore instead of a moons file.
There are other examples that would work equally well (or better) for this purpose but is it worth doing a overhaul on large parts of the lesson materials?
There doesn't seem to be overwhelming support for an overhaul, so I vote for leaving as-is.
I recall from some instructor discussion sessions that someone (can't remember who, sorry!) has used a guacamole recipe as the base document and then added a file with ingredients and that seemed to go over well. If anyone else has any data points (has used that example or knows from whence it came), please chime in.
Yes, that's the lesson that I use sometimes. I started using it at a workshop for high-school kids (I thought the planets story was a bit alien for them and someone who was helping mentioned he's seen a something like that somewhere).
I don't have a lesson in writing: I just do it every time from scratch. The story is simpler and, because it's somewhat unexpected, softens a bit the harshness that Git brings in. It gets people off guard and I think the less technical people feel it a bit closer to them and are less intimidated.
Basically you have two files (ingredients.txt and methods.txt), which hold a short ingredient list and a few steps with the preparations.
The files are really short, which it's good because saves a lot of typing. As most people have an opinion on the recipe, they don't feel the need to use my very same text. This is great for bad typists, people with bad sight, etc... as they don't have the pressure to type exactly what I do.
The two files must be kept in sync (if you add salt as a new ingredient, you should include a new step in the recipe). This is similar to many real projects (a paper and its biblio, a Python module with a library and the script using the library, some parameters in a file and model) and makes very natural the introduction of the staging area.
For the "ignore" part, I use a empty file called secret_sauce.txt that I don't want people to see. For the "undo changes" part, I add some poisonous ingredient and then remove it in several ways.
The collaboration part goes usually ok, because people is really into changing other persons' recipe.
The best part for me is that it has really few constrains for the instructor and very little extra load in the learners and instructor's head. In general, I always have trouble reading my notes, talking, and typing at the same time (I type bad and English is not my first language, so teaching 3-hours in a row is always demanding.) The few brain cycles that I save by not having to remember exactly what to type, or be witty enough to make meaningful sentences for new commits, or read my notes, allows me to focus in the lesson and do a much better job (I think).
I'll write up a better description in the instructor's guide soon.
I changed the story-example for my tutorial on EuroScipy, https://github.com/rgaiacs/swc-git-novice-euroscipy2016, and I spent 30-60min to change the things with sed. When we agree on the changes I volunteer to implement it.
Transferring from email chain - We’ve also been experimenting with a Dracula/Wolfman free git lesson, but in the context of a Data Carpentry workshop. Git isn’t a standard part of the curriculum, and there isn’t time to do both command line and git (we tried). We ended up using the new GitHub Desktop GUI client (https://github.com/desktop/desktop), which is open source. Using a GUI makes it much easier to explain for new learners. We replaced the story line with editing a data set and the README file for the repo. Our repo is at https://github.com/caltechlibrary/git-desktop and comments are welcome.
Thanks @tmorrell. @tracykteal this is potentially a great lesson that people teaching the ecology workshop should be aware of? We often like to add other lessons when we run a longer workshop and this one will work very well for those who want to teach version control in an extended workshop?
As per my comment on the discuss list, I'd be happy to organise a 2-day sprint to get the basics of a new git/github lesson together based on suggestions in the discussion available at [1] and [2] with subject "Git lesson alternative"
Potential dates: 31 Aug & 1 Sept (or around those dates).
[1] http://lists.software-carpentry.org/pipermail/discuss/2017-August/005393.html [2] http://lists.software-carpentry.org/pipermail/discuss/2017-July/thread.html#5336
Apologies if this has already been suggested, but what about using git to version control a "simple" bash script? Learners will have just seen bash prior to the git lesson. It would theoretically be a more authentic task, without introducing new cognitive load (assuming, of course, that learners understood the bash scripting lesson).
I think that the assumption that students will have already absorbed and processed the bash lesson is a bit of a high expectation, and will make people who feel like they didn't absorb that lesson quite yet feel like they're already flailing.
Personally, I sort of play it by ear and do some variant of the planets thing without invoking Dracula and Wolfman. I've had students write each other knock-knock jokes as part of the collaborative push-pull lesson, which is also fun.
A bit of a bump from a year ago:
I very much like @iglpdc 's guacamole recipe example for git. For all the reasons he listed, plus it's easy to modify and forgiving when I forget the order of events.
Learners have fun with collaborating on each other's recipes and there's little to no cognitive load spent on the content of the files.
For anyone who's interested, I made a written version of the git lesson based on @iglpdc 's guacamole example. I implemented it a bit differently than @iglpdc describes, mostly because I was trying to keep closely to the current lesson format. I didn't emphasize keeping a methods file and an ingredients file in sync, and my ignore example was a bit trivial.
I taught from this version yesterday, which was also my first time teaching git. It seemed to go well. I remember from encountering the planets git lesson as a learner that it felt confusing, and tracking the story line took effort. I think editing a guacamole recipe is less cognitive load. Learners had strong differences of opinion on suitable ingredients, so that injected some levity after two long days of coding. (This was the first time I'd heard the word "blasphemy" used at a workshop...) My co-instructor and I used two projectors to show both our screens as we walked through collaboration and conflict.
I liked being able to introduce the concept of version control for solo projects and then, later, after we'd gone over the commit cycle, introduce how we could use the same software to collaborate with others. The planets version talks about collaboration right from the beginning, and I wonder if that's not too many new concepts at one time for some learners. I also spent a few minutes at the beginning of the lesson showing various GitHub repos and discussing how some of them were used by large consortiums to enable collaboration on code while others were used by just one person for the sake of having backups and a visible record of the project over time.
Comments, suggestions, and pull requests are welcome! Also, @iglpdc , I wanted to credit you for the inspiration but wasn't sure what the accepted mode was...
I'm not sure where else to put this, so I'll do so here. I've taught the git lesson a few times and while I do appreciate the intention behind the "childish, approachable" goal, the feedback about the narrative has been overwhelmingly negative. Mostly in the context that people had a harder time imagining this being relevant for their work.
What I ended up doing as an alternative in a trial lesson was to have people create a markdown file instead of a text file, and document the git commands they were learning as they learned them. This was received very positively. It isn't perfect by any means, but in my limited experience it was definitely an improvement. I'm not sure whether there's interest in that amount of change for this lesson, but I thought I'd offer it here since others have made their own changes. It's just instructor notes, I didn't actually update the repo episode markdown pages themselves since it was a trial.
What about a "stone soup" recipe instead of guacamole? I feel like the story lends itself to people contributing a bunch of arbitrary things and is pretty inclusive.
I also like the "stone soup" idea. It seems particularly good since it's a story that appears in many different cultures.
I think alpha/beta testing storyline patches before we merge them in will be very valuable. Do we have a framework for doing that systematically? Planets, guacamole, and python/R scripts based git lessons have all been tried out in the past, so it would be nice to compare real-world experiences with each.
I changed it to "alpha/beta" for my workshop (not official SWC but uses its materials) and no one complained. Incidentally, I chose "alpha/beta" independently before knowing such discussions already existed here.
Just to add my two cents...
- At first I was very worried that the Dracula/Wolfman narrative wouldn't translate well to Spanish; however, the group I'm working with to the Spanish lessons seems to think its okay, and one of my co-instructors is actually named Vladamir!
- However, whether or not the story has worked well in the past, I think the points that people bring up about inclusivity (all the characters are male) and relatability (its a childish story about space) are reason enough to change the storyline.
- As much as I love guacamole, I'm not convinced this is a great option, because there aren't that many ingredients or steps to make it. For example, in Argentina, its just avocado, olive oil, salt, and pepper.
What would it take to revamp the entire lesson around a new motiving story? What is the timeline?
- As much as I love guacamole, I'm not convinced this is a great option, because there aren't that many ingredients or steps to make it. For example, in Argentina, its just avocado, olive oil, salt, and pepper.
So maybe a different (more universal) recipe, then?
Yes @bsmith89. There was some enthusiasm for the stone soup story mentioned above by @daisieh. I like this because the instructor can start making the soup by beginning with a pot, boiling water, and a stone. Then can add some something like carrots and seasoning. Then, the learners can add whatever comes to their imaginations.
I don't like the use of a story, because it requires people to keep track of that story for it to make sense - extra cognitive load. I do like the idea of a recipe (and if I remember correctly, in the mists of time before we had the planets, there used to be a soup recipe in this lesson)
How about asking learners to copy-paste some parts of their home institution's profile / self-description? In my case: tib.eu/en/tib/profile. This can be used to step-by-step build a ReadMe.md with content they can relate to while not having to think about. Introducing a typo can be a segway to pair learners up for fixing them through GitHub-PRs.
I think in this continuing discussion, it might be worth creating a branch to develop an alternative.
Regarding stories and cognitive load. Regardless of what we include as text in the files used to teach git, it will add some type of cognitive load. The question is, “what is the least and most appropriate?”
To add code would add a high level of cognitive load to the learners. They are usually novices, and not well versed in code. They will either completely dismiss the code as gobblygook, which will make it harder to learn later; or get sidetracked into "what does this mean," which is not the point of this lesson.
Stories - especially folklore, fairy tales, etc - work well to provide low cognitive. The idea of folklore and fairy tales are cross-cultural, with many specific stories appearing across many cultures with slight variations. This idea is not something new to most people, which is why it creates low cognitive load. The "monsters go to Mars" story accomplishes this. To give anecdotal evidence, the workshops I lead have a very high attendance rate for our git lessons, and our student body is very diverse (one of the top 10 diverse student bodies in the United States); this is to say, our learners have a variety of cultural backgrounds. I have only experienced once when a learner, during the break, questioned who Dracula and these others were. When we explained they were folklore monsters from a European tradition, he nodded and smiled because he realized he didn’t have to worry about it for the lesson. We haven’t had other questions, and at the beginning of our workshops (and often reinforced throughout), we explain that the examples used in the lesson don’t matter, but are a discipline agnostic way of presenting how to do [git, bash, python, r, etc].
That said, I am not opposed to using a different story to teach git. I am opposed to using code or something along those lines to teach git, because that will absolutely introduce high cognitive load to learners.
I think stone soup is a good alternative story, and will also add interactivity with the learners.
At my university, we've been teaching the "guacamole" lesson since a long time ago (at least since I saw @iglpdc's comment above). But its content was shared internally in a single file between our local instructors. It was not until now when we were having an instructor from outside our group that I did the step and made it properly using the lesson template. We've only changed the story and the content of the files used. Since this lesson then teaches GitHub, the format used for the files is md so it renders then nicely. I'm happy to open a PR (though I'd need to remove a bit from the README first).
- This is the comparisson
- Rendered lesson
- Socrative questions for this variation - SOC-25839789
From my experience having taught both lessons, I've found that the students engaged a lot better with the recipes as everyone was writing the same content. When they do the contribute on GitHub exercise I ask them to write their favourite recipe. This is very nice when you have students from different cultures as they share their favourite plate from their place.
I have also taught using @iglpdc's git guacamole lesson since 2015 and the main advantage for me has been a lot less typing, which allows non-native English speakers to keep up. Creating a list of ingredients is not much to type, and neither is composing a short recipe using those ingredients.
I've made some changes to @dpshelio's excellent guacamole adaptation and taught it in August this year, with great results. In their feedback learners appreciated the recipe metaphor and found it easy to understand. Please feel free to adapt and use for your own lessons:
- Repo: https://github.com/UoA-eResearch/git-novice.
- Rendered lesson: https://uoa-eresearch.github.io/git-novice/
These are the changed we've made:
- I moved the SSH key creation portion from lesson 8 - Collaborating, to lesson 2 - Setting Up Git. We found this reduced cognitive load and our learners had more success. See #976.
- Swapped researcher names for gender balance - Sarah and Kai.
- Swapped guacamole for a soup recipe for majority of the lesson as some comments here have also proposed, as it is a more universal dish and our learners come from different cultural backgrounds. It naturally illustrates why conflicts arise, because different people and cultures have different soup ingredients. We still used guacamole for the Conflict lesson, but I showed a picture of guacamole before we taught it. In learner feedback we found at least one learner probably didn't know what guacamole was before the lesson!
I taught planets in a previous lesson and while I personally like the whimsical nature of the story and it largely did not interfere with progress through the lesson, I think recipes can better illustrate the usefulness of Git to a learner cohort with diverse backgrounds.
I also tought planets recently, and I think especially the not so sci-fi minded people felt a pretty strong disconnect from the story. Some direct feedback from that workshop was to better illustrate the usefulness of git for every day problems/tasks the learners face.
