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

Pointer to let the group keep up #304

Open
TomKellyGenetics opened this Issue Jul 5, 2016 · 12 comments

Comments

Projects
None yet
@TomKellyGenetics
Contributor

TomKellyGenetics commented Jul 5, 2016

Tried my hand at being Instructor for git at SWC Otago rather than my usual R. I had a few issues with the pace of the group varying wildly and I'd like to raise some potential solutions for discussion among git instructors.

When you're teaching R in the RStudio IDE, you can have the script and command windows separate. This way we can run commands with loads of input, learners can still see the command that generated it. This has the added bonuses of leaving recently run commands above so that learners lagging behind can work through them at their own pace and enabling helpers to better troubleshoot issues. Similar set ups can be achieved in iPython Notebooks and it isn't really necessary in bash, rarely generating such a large output until learners are building up scripts themselves.

However, I found the git lessons more challenging to pace in this regard. With git log and git status commands to show where we are quickly crowding out the history. We tried to integrate the git and bash lessons with me taking over the previous instructor's machine to have the same file structure as the participants. This merely exacerbated the issue with Mac printing git log to the terminal so I couldn't return and continue to the previous commands with q as I would do in Linux.

I tried to stick to my RStudio style of running several commands and pausing to explain what we'd done and what we would need to do next. It quickly didn't work. I improvised with clear and history -n 10 and used it profusely to restore our session so learners could follow along for mini-tasks rather than line-by-line (say checkout a branch, make a commit, and check the new log). This worked somewhat and even got several special mentions in the feedback. Some even used history themselves to adapt their loops into scripts as we were doing in a later lesson. Our instructor for the second half of git used zsh which alleviated some of the need for ls, pwd, git status commands and it seemed to work but I'm unsure that fits in the realm of Software Carpentry.

Another solution I came up with to maximise the time showing previous commands for learners to follow along was to edit text using redirects and appends echo "example text" > file.txt rather than an editor so the editor didn't hide the terminal. However this backfired, I was able to go faster, while many learners were fretting about the syntax of the arbitrary strings as carefully as commands they'd just learned in the bash lesson rather than focusing on git at the level of files.

Both of these were ad-hoc solutions so I was wondering whether others could benefit from these pointers or had suggestions for solutions of their own. My aims were simple:

  • have a history of the recently run commands for learners to follow
  • have text large enough to view at the back of a class of 40-60 people

I have heard of convoluted .bashrc set ups but I'd rather a solution which does not reconfigure an instructor's personal machine. A similar set up to RStudio (pushing commands from a text window to a terminal) could be suitable if the text were large enough but copy/paste seems rather crude.

The main take-home message is that the best way to code is not the best way to live-code for a class. Any Suggestions?

@dme26

This comment has been minimized.

dme26 commented Jul 5, 2016

Hi Tom, one very minor point regarding the follow-on git session: I was running bash rather than zsh with the basic PS1='$ '. You're right that I popped into zsh at one point though, due to a misfire on my part—I had a mid-demo mental blank when I needed to recap the --staged flag to git diff, so I visited zsh to give me tab completion and then returned to bash. I probably should have done that on a private window and paused my "thinking aloud" though!

@dme26

This comment has been minimized.

dme26 commented Jul 5, 2016

I know that some of the more advanced terminal emulators out there (e.g. https://www.iterm2.com/ for MacOS) have shell integration that might allow for effective navigation, annotation, summarisation, etc., of command output... but of course it's not desirable to be using platform-specific software that behaves vastly differently from the default terminal emulators that are available on the usual collection of OSs seen...

@gcapes

This comment has been minimized.

gcapes commented Jul 5, 2016

I think you've nearly solved this problem already. Using clear and history are useful to summarise what you've just done. For learners who are falling behind: all the commands are in the lesson notes. Provide a link to the lesson before you start, then learners can follow along and refer back as required.

@justbennet

This comment has been minimized.

Contributor

justbennet commented Jul 5, 2016

Just out of curiosity, did you look into using Git from within R Studio? That gives you some access to the Git commands. I understand that it isn't full-on Git from the command line, and it may be a bit of a transition from Git in Rstudio to Git at the command line. I'm not advocating its real use, just wondering whether it got an evaluation.

What would happen if you used RStudio to do the editing and kept the terminal window for just the Git? That gives them an editor they're familiar with, and if you go back over the exact same material that was developed in the R portion of the workshop, it's also reinforcing what they've learned. The issue with that, of course, is that you have to switch windows, which may be even more jarring than staying entirely in the terminal. My experience is that most projection setups are single-window if you get the typeface large enough to be read from the back row.

I understand and mostly agree that using R Studio generally leads to better retention by the learners, but it is teaching from a GUI, which makes the parts that use the shell more obtrusive and less well-connected. I think this topic is part of the broader one of creating better cohesion among the parts of the workshop if using a GUI (whether RStudio, Spyder, Canopy, Eclipse) for half of it and the command line for half.

As a hint at a follow-on topic, what does using the GUI do to the goal of showing people 'automation', which I think of as work from the command line? Do people typically show how to use R from the command line and from a script when they teach? Did you?

P.S. dme26, I agree that it's probably a good idea to avoid depending on additional software and modifying a user's basic environment.

@lexnederbragt

This comment has been minimized.

Member

lexnederbragt commented Jul 5, 2016

I don't have the same experience with learners getting lost after several commands - at least for the standard git lesson (that does not do any branching). I usually take it quite slow, and there are not that many commands. In addition to pointing learners to the lesson website, you could also ask learners or a helper to mirror all commands in the etherpad. Finally, whenever I modify a text file, after I close the editor (nano), I run cat to show the final content in the terminal (following the novice lesson, you'll have at most four lines of text).

@thomasballinger

This comment has been minimized.

thomasballinger commented Jul 5, 2016

In (non-SWC) git sessions I've run, I've used gitk (a read-only graphical git client that comes with most installations of git) as my ls equivalent: we run one command, then look at it again. The command we run is "gitk --all" because like git log, it shows from head back without this flag.

@wrightaprilm

This comment has been minimized.

wrightaprilm commented Jul 5, 2016

This somehow became a wall of test. Sorry.

Firstly, I think you should cut yourself some slack with regards to being thrown off your game using someone else's computer. That's hard. I recently had to teach from someone else's computer and never really got used to it. You do your best with what you have.

Secondly, I think with the git materials, it's really important to decide what and how much your learners need to know. A lot of us often joke that Software Carpentry is about getting people to the point where they can google. And I think that's especially true of Git, since the syntax and concept are probably pretty alien to a lot of learners. A strong, simple narrative or use case can be really helpful here. I recently taught a Data Carpentry workshop (shell and git are not parts of the core curriculum, but had been requested) where we did an abbreviated shell (one hour) and a two hour git lesson. The narrative for the git lesson was to make some commits, learn to push them to remote, and then make a static website explaining what our code project was doing. And that was the perfect for amount of content for two hours. Instead of planets, we used the R script they'd been working on in the previous two sessions. That was a good jumping-off point as most of them had, by the end of the second day, made a mistake they'd like to roll back. The idea of pushing to a remote was nice for most of them, as they have collaborators in other places. The static website for a project was a hit.

I unfortunately taught my session entirely extemporaneously, and don't have the lesson materials.

Thirdly, I agree with @lexnederbragt that I've not had the issue of learners being lost every few commands with the git lesson. There are pretty few commands. I think the key here is to be really explaining each command as your do it. There has been some discussion on the listserve about tools to automatically echo commands to a file that you can upload to the course website (Zbigniew Jędrzejewski-Szmek recently posted a new one and discussed it on [Discuss]). But really, I think moving slowly through a small set of commands is the right thing to do here.

I'm confused as to why we would want to alleviate the need for pwd, ls, history, etc. These are all really useful commands, and I don't think you need to be embarrassed about using useful commands during your lesson.

Lastly:

The main take-home message is that the best way to code is not the best way to live-code for a class. Any Suggestions?

I don't think the issue here is live-coding, it sounds like it's going off-script? Going off-script when you're not that familiar with the cadence of the material is really challenging, and thinking 'Oh, I can show this real quick, even though it's not in the lesson' has gotten me in trouble before. I think SWC even has some guidelines about how many workshops you need to have taught before adding your own homebrew to the menu. Before going off-script, I always think to myself 'Hey, I really shouldn't do this', and then do it anyway. Don't beat yourself up too hard, but I think definitely take your lessons from this situation and go forward with a clear and simple narrative for the git lesson. It really does help.

@willingc

This comment has been minimized.

Member

willingc commented Jul 5, 2016

I frequently teach git and GitHub to new developers and scientists. I focus less on the "hands on" initially.

I emphasize two key concepts at the start:

  • understanding local and remotes (in the context of contributing to an open source project)
  • the importance of git status git remote -v git log - use often to understand what is going on

I save the "hands on" until the end or after the second half of the slide deck. Here's the slide deck: http://www.slideshare.net/willingc/yes-you-can-git

@iglpdc

This comment has been minimized.

Contributor

iglpdc commented Jul 5, 2016

In addition to all said, a good way of solving this is to split your terminal and show the last 5-ish commands run in one of the splits. You loose some real state in the screen, but give a great picture of what you are doing. This is specially helpful for git, because command outputs are really long but the workflows tend to be very short (a full commit cycle can be 3-5 commands).

We have an open issue for one possible implementation #163 , any takers? ;-)

@iglpdc

This comment has been minimized.

Contributor

iglpdc commented Jul 5, 2016

And, yes, the size of the terminal font should be huge: I usually set mine so it fits only 15 lines or so. Using "PS1=$ " (your prompt is just the dollar sign) is important, but tell the learners not to do so.

Also, tell the students that they can make their terminals larger. Some people get really small terminals by default (I think Git Bash is the worst, but Macs are pretty bad too) and have a hard time reading and writing on them.

@TomKellyGenetics

This comment has been minimized.

Contributor

TomKellyGenetics commented Jul 5, 2016

Hi All,

Thanks for the feedback. Perhaps I did indeed just go too fast, it was my first time doing this session.

@justbennet We tried showing git in the terminal after the bash lesson and calling back to the git concepts when introducing Projects in RStudio. We generally teach R as interactive, exploratory analysis (how it is used in our field), with emphasis on reproducible record of commands in the script window. We tend to leave the automation theme for when focusing on bash scripts as it's a more alien concept to our biologist-dominated audiences.

Great to see so much discussion spawning from this while NZ was asleep.

@kevin-vilbig

This comment has been minimized.

kevin-vilbig commented Jul 7, 2016

Here is a tip from @k8hertweck that I've def. started to use. It keeps a history that you then share with your class so that they can check back on their own if they are behind. You need to have Dropbox set up and etc, but it is incredibly helpful.

export PROMPT_COMMAND="history 1 >> ~/Dropbox/UnixHistory.txt"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment