New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Should we change the story behind the lesson? #277

Open
iglpdc opened this Issue Jun 6, 2016 · 25 comments

Comments

Projects
None yet
@iglpdc
Contributor

iglpdc commented Jun 6, 2016

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 .txt files;
  • 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.

@iglpdc iglpdc added the discussion label Jun 6, 2016

@iglpdc iglpdc added this to the Version 5.4 milestone Jun 6, 2016

@pschloss

This comment has been minimized.

pschloss commented Jun 13, 2016

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.

@guyer

This comment has been minimized.

guyer commented Jun 13, 2016

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.

@TomKellyGenetics

This comment has been minimized.

Contributor

TomKellyGenetics commented Jul 6, 2016

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?

@gvwilson

This comment has been minimized.

Member

gvwilson commented Aug 1, 2016

There doesn't seem to be overwhelming support for an overhaul, so I vote for leaving as-is.

@ChristinaLK

This comment has been minimized.

ChristinaLK commented Aug 1, 2016

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.

@iglpdc

This comment has been minimized.

Contributor

iglpdc commented Aug 1, 2016

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.

@rgaiacs

This comment has been minimized.

Contributor

rgaiacs commented Aug 27, 2016

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.

@tmorrell

This comment has been minimized.

Contributor

tmorrell commented Jul 31, 2017

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.

@anelda

This comment has been minimized.

Contributor

anelda commented Aug 1, 2017

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?

@anelda

This comment has been minimized.

Contributor

anelda commented Aug 1, 2017

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

@ErinBecker

This comment has been minimized.

Collaborator

ErinBecker commented Aug 1, 2017

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).

@daisieh

This comment has been minimized.

Contributor

daisieh commented Aug 2, 2017

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.

@bsmith89

This comment has been minimized.

bsmith89 commented Aug 2, 2017

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.

@rrlove

This comment has been minimized.

rrlove commented Aug 9, 2017

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...

@mcritchlow

This comment has been minimized.

Contributor

mcritchlow commented Dec 13, 2017

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.

@pllim

This comment has been minimized.

Contributor

pllim commented Feb 9, 2018

👍 to changing the characters to be more inclusive.

@daisieh

This comment has been minimized.

Contributor

daisieh commented Feb 11, 2018

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.

@tracykteal

This comment has been minimized.

Contributor

tracykteal commented Feb 13, 2018

I also like the "stone soup" idea. It seems particularly good since it's a story that appears in many different cultures.

@bsmith89

This comment has been minimized.

bsmith89 commented Feb 14, 2018

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.

@pllim

This comment has been minimized.

Contributor

pllim commented Feb 15, 2018

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.

@iglpdc iglpdc added type:discussion and removed discussion labels Mar 22, 2018

@raynamharris

This comment has been minimized.

Contributor

raynamharris commented Apr 6, 2018

Just to add my two cents...

  1. 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!
  2. 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.
  3. 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?

@bsmith89

This comment has been minimized.

bsmith89 commented Apr 6, 2018

  1. 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?

@raynamharris

This comment has been minimized.

Contributor

raynamharris commented Apr 6, 2018

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.

fmichonneau pushed a commit that referenced this issue Jun 19, 2018

Merge pull request #277 from rgaiacs/bin-python3
Change shebang to Python3
@swaldman3

This comment has been minimized.

Member

swaldman3 commented Nov 3, 2018

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)

@katrinleinweber

This comment has been minimized.

Contributor

katrinleinweber commented Nov 7, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment