Create introductory motivational slides for topics

[gvwilson]

The creating-slides-for-lessons branch in this repository contains a directory called slides, within which are the beginnings of short slide decks to introduce Software Carpentry as a whole, and each of the particular novice topics. More slide decks need to be created to give a two-minute introduction to:

• [ ] Python
• [ ] R
• [ ] Git
• [ ] SQL

[davclark]

Pending agreement from my collaborator (@publicus, I think - Jacob Levernier), I'm thinking I'll work on (part of) this for my instructor training project. I already have a bunch of slides that I want to convert to reveal.js (or impress.js)?

I'd particularly like to tie in to @tracykteal & co's "Data Carpentry" initiative. I have some good material on that (though it's not one of the four topics above). I'm also open to doing some work on Python and Git.

[gvwilson]

Please use the existing slides/shell.html as a template for both layout and level - we really want to keep it short and simple, and directly tied to the particular topic.

[tracykteal]

Great, and will be interested to see what you have.

[jglev]

To confirm, I'm on board to work on this with @davclark!

[DevasenaInupakutika]

I'm working on Python and R slides with @danlwarren

[davclark]

I just saw @DevasenaInupakutika's comment. It would be good to know where R and Python development is happening. Perhaps @publicus and I should focus on git?

Generally, for a project of this size, I think forking, working in a branch, then doing a pull-request is the way to go. BUT, there is already a creating-slides-for-lessons branch, and perhaps we should just all work there and try to keep our history linear (using git pull --rebase or similar)?

[davclark]

Also, for folks that are new to jekyll (which, for software carpentry, is what is used to host sites here on GitHub pages), you need to deal with a little ruby on the development end. In particular, you can get everything you need by doing a gem install github-pages (which is maintained here, but doesn't seem to be directly linked from the GitHub pages docs anymore). Once this is installed properly, you can run jekyll serve -w and changes to the slides will be immediately updated at localhost:4000.

If you're new to ruby, you can not worry about managing different sets of libraries. But if you want to enable multiple sets of libraries (like in a virtualenv), I use rbenv. You may also come across RVM. It does things like redefine cd. Enough said.

I guess we should document this somewhere? Should this go in a readme in the slides directory?

[timClicks]

Sorry if this is a silly question, but is there an 'agreed' set of motivations for each of those topics that we're writing up, or are the motivations being drafted as well as the slides?

[jglev]

@timClicks: I had the same question, too. My assumption is that motivations are to be drafted, as well, and can be replaced in the future if better / more motivating motivations come up in the future. @gvwilson, is that correct?

[jglev]

@davclark and I have agreed to work on Git and SQL slides, respectively, since @DevasenaInupakutika and @danlwarren have Python and R covered.

[wking]

The existing motivation is likely laid out in the best-practices paper [1,2,3,4]. There's also good stuff in the “Learning objectives” and “Key points” portions of the old instructor's guide 5. I tried to condense this information (for version-control anyway) in my subject/tool structure (#102), if you want to look at that too [6,7].

[gvwilson]

Sorry to be so slow replying (post-Canada Day mail catchup). Yes, you'll need to come up with "why you'd want to learn this" points - some of the novice lessons have this in their first few paragraphs, or right at the end, but not all, and it's usually not highlighted.

[davclark]

I promised @publicus I'd have a look at how to do slides in Markdown. As far as I can see, there's no way to iterate over individual YAML documents (unfortunately, what YAML calls the data between --- delimiters, I'm not talking about the HTML document). So, for Jekyll (/ liquid templates) you need to use the capture / mardownify machinery. This is less readable than just coding the HTML.

But, it turns out reveal.js also supports Markdown. The syntax to do fragments, however, is clunky. In particular, it grabs the smallest scope HTML element it can. You'll see an illustration of how this interacts with emphasis in a bullet-list in the current git.html.

The downside here is that it's still not really much more readable than HTML, and now we're using two different markdown parsers (though it tries to do GitHub style). See here for more info on exactly how reveal.js parses Markdown.

Another compromise would be to use non XHTML <li> elements. This saves 4 characters per item.

If we want to stick with Markdown, I think we should not use reveal.js fragment annotation, but rather just have a jquery script that goes and adds the fragment class to non-initial <li> elements. But I've done enough futzing for now, so I'll see what others think about slide format before doing more.

[gvwilson]

I vote for using plain old HTML for the slides - they're short enough that the extra editing shouldn't be a problem.

[ramnathv]

If you are looking to convert from R Markdown to HTML, I have an R package named slidify that does the conversion and supports most of the popular HTML5 presentation frameworks.

[gvwilson]

I would prefer us to use straight HTML for our reveal.js slides.

[timClicks]

I'll pull myself away from this issue, as it looks like all of the points are already being worked on by others.

[danlwarren]

We're a bit confused about how far we should depart from the format of the shell demo slides. Can we include images, or should we just be going with formatted text?

[danlwarren]

Second bit of clarification: The title of this thread is specifically about motivational slides, but then the description of the work (and the shell.html demo) are a short introduction - not just motivation, but a bit of detail. Should we be doing motivation only, or should we do more of a complete introduction?

[gvwilson]

Images are very welcome!

[gvwilson]

Honest answer is, I'm not sure what balance to strike between "here's what we're going to show you" and "here's how it will make your life better". What would you say in the first few minutes of each tutorial to get people oriented and excited?

[chendaniely]

We used an example during the Rockefeller workshop that 'got them to see the light' by having them to move a pattern of files from a directory of 40k files.

The gui takes forever to even draw the icons to screen, if it doesn't end up crashing.

[DevasenaInupakutika]

R motivational slides submitted as a pull request here. Any suggestions, comments and feedback would be much appreciated. https://github.com/swcarpentry/bc/pull/628

[davclark]

So, I'm finally working on this, and I'll probably shelve it again because I want to have slides without visual artifacts for Monday, and right now, the footer doens't layout reliably and it interacts with content image scaling and cuts off the bottom of an image I want to use.

So, I can provide a pointer to the content I'm using. Is anyone working on improving the slide layout? It's fairly well outside my expertise, and so I probably shouldn't do it. I might be able to talk my wife into helping, though.

In the same vicinity, even on my ridiculous late-model i7 macbook retina, generating pages takes a LONG time. And jekyll -w doesn't pick up changes to the CSS. Any tips on doing faster iterative development?

For now, I'm mostly editing CSS attributes in the "Inspect Elements" dialogue in Chrome - but I can lose track of what I'm doing that way...

[davclark]

I suppose I should also nudge my compatriot in this particular assignment - @publicus, any progress on your end?

[gvwilson]

If you can get plain old HTML for the points and the speaker's notes into the PR, I'll take care of the formatting...

[DevasenaInupakutika]

Hello all,

Updated R motivational slides (as per inputs from all) are present here. https://github.com/swcarpentry/bc/pull/628#

Could you please have a look at it and merge pull request if everything looks fine.

Thanks!

[jglev]

@davclark , I'm just getting to work on this, as well -- the summer teaching term just ended, and all of the term papers are graded, so I'm ready to get back to it : )

[jglev]

Just a quick update that I finally have a draft for SQL up and running, at https://github.com/publicus/bc/blob/adding_slides_for_sql/slides/introduction_to_sql.html . @davclark, I'll send you an email to talk more, if you have feedback on this initial draft.