JOSE Submission Inquiry: Tutorial slide deck + single script

[moorepants]

I have a slidedeck for a ~5-6 hour workshop/tutorial and a single R script that I share with students after the course is done. The goal is to write the R script live during the tutorial with the student's data.

I'm curious if something like this is acceptable to submit? There are really aren't any "open sources" for the teaching materials per se.

Slidedeck: https://tinyurl.com/squiggly-cosmos2018

R script: https://gist.github.com/moorepants/a19128a8edabd6f02ec7d38b8331b1d4

[moorepants]

I was reading this statement on the website:

The tl;dr; implies that the submitted content only needs to include code to qualify, but the first paragraph seems to say that specific types of content that are generated from a text-based source is what we are looking for.

Things like LaTeX, R Markdown, and ReST all have a "source" which is used to generate some type of final presentation form of the materials. The Jupyter notebook is similar but different in that the user doesn't edit the raw source (json) directly, but portions of it via a GUI.

The submission idea I have above has no source text that is used to generate the presentation materials. I choose to write it in WYSIWG Google slides for convenience, lack of time, and quality. But this example is very much a "coding to learn" material set.

So I'm confused on whether something like this would fit the current wording on the website. Currently it seems a submission needs both the following to qualify:

• primary learning materials must be created from a text based source
• primary learning materials must contain or use code

In this case, it only meets the second item. I suppose I could rewrite the slides with something like Beamer or Rise to hit both, but that doesn't seem to offer much to the content author. I'd personally like to advocate that we not be strict on their being a "source". As a teacher, I might want to teach using code but not write my primary materials in some kind of text based tool. The journal title also has the words "Open Source" in it, thus it is also implied that there is a "source" and that it is "open". There must be a difference between "Open Source Educational Materials" and "Open Educational Resources" (traditionally coined name). I assume it is the "source".

Anyways, some clarity here would help. I brought this up to Kyle at SciPy 2017 when the whole idea of JOSE was floated. I was concerned that having "source" in the title could be quite limiting, being that teachers don't always have a source for their materials but that they teach in the way that I think we see as in scope for the journal.

[moorepants]

Just noticed this a bit further down:

which confuses me more, but it now uses the OER term, which doesn't imply a "source".

[kyleniemeyer]

@labarba may want to chime in, but we decided early on that content that only includes presentation materials (slides, notes) is not in scope. Submissions need to rely heavily on programming to teach concepts.

[moorepants]

These slides do rely heavily on programming to teach. In this case, the students are programming almost continuously throughout the tutorial, but are only shown the slides and live programming in RStudio by the instructor (which amounts to the provided complete R script). It is only that the slides are not generated from some text based source. Even if the slides were generated from a text based source, this is something students would never be aware of, so it isn't clear to me how this matters.

An analogy would be if a Software Carpentry lesson designer typed up one of the lessons in MS Word and exported to HTML to host on the SWC website instead of typing it in Markdown (or whatever lightweight markup language they use) and converted to HTML and hosted on the site. The learners never view the markdown (or the MS Word file), only the HTML page, maybe some slides, maybe some live board work, and the live coding of the teacher.

[labarba]

Your enquiry really raises the issue of reuse. Every instructor knows that it is very hard to use someone else's slides to teach. It is also very difficult to modify and/or remix them.

So, yes, we were thinking of learning modules being written out in a plain-text underlying format. In my opinion, slide decks, on their own, are not a good fit for publication in JOSE, and we consider them "supplementary materials."

I realize that readers of the guideline can pick it apart and discover various points of ambiguity. Our current version is the first attempt at explaining our scope, and surely needs improvement.

The use of the term OER is intended to convey the sharing under the "5R" permissions http://opencontent.org/definition/
... but beyond permissions, technical choices can and do make content more or less open.

[tracykteal]

The intent of all this, is, as Lorena says, about reuse for an instructor. Are the materials editable by another for their own use, and also can another instructor understand how to use the materials without talking with you.

I'm curious what other editors think, but I think a Google slide deck could be a re-usable resource, with explanatory information. Could you for instance make a repository for this course, and have a README or other pages that explains about the course and how to use the materials? It could link to a generalized Google slide deck, with the instructions that say 'make a copy of this slide deck, then modify as needed'. And for instance in that About Me slide, rather than having it about you, having 'put your information here'. In that 'how to use these materials' resource, you would need information on how to use the slide deck, including potentially essentially what you say for each slide and how you integrate the code into the discussion. You're right that the learners experience Software Carpentry materials as an HTML page, but the instructor is reading through all the text to understand how to understand and present the materials, and that is what makes them usable by many people.

[moorepants]

Thanks for the comments. Thinking from a reuse perspective and whether the technical choices make it easier or harder to reuse is helpful. The "Poor Technical Choices" section of the open content definition Lorena shared has good probing questions for an author to think about that aspect. The question of open format or not (e.g. ODT vs DOCX) and whether it is technically easy to edit, modify, remix (e.g Blender(hard) vs Sketchup(easy) or Beamer(hard) vs Impress(easy)) were the main two things that it brought to mind.

I think that the about section on the JOSE website could use some language that highlights the reuse ideas and pulls from the link Lorena shared. This would help frame why we only accept certain types of content (created with a set of technical tools, i.e. maybe "can only use a text based editor to manipulate"). Once it is clearer to me what exactly this is, I'm happy to take a shot at adding this.

I personally find a slide deck (G-Slides, Impress, PPT) much easier to reuse and remix than many of the text source based presentations tools. Using the open presentation format (Impress) is probably the best file format since G-Slides and PPT are proprietary, based on the questions in the ""Poor Technical Choices" section. So those questions in the link would point me towards an Impress Slidedeck.

Currently all I have above is a slide deck (sans notes) and an R script (code guide for the instructor). I had imagined writing instructor instructions as Tracy suggests in the paper.md and/or as slide notes or a separate instructor guide. If I add the instructor guide (any any form) would that make this sufficient for submission? Or maybe a specific technical form of the instructor guide would be required?

One last thought: teaching materials don't necessarily have to be code to teach code. I recall learning Matlab for the first time from scanned PDFs of a teacher's handwritten notes which he'd display via the projector. It wasn't the best set of teaching materials, but I did learn to write basic numerical algs in Matlab.

[labarba]

We also want a learning module to be usable for a self-learner. So I still maintain that a slide deck with instructor notes is insufficient.

[moorepants]

Ok, the self-learner aspect is a key note! That also needs to be elaborated in the about prose. That makes a big difference. I wasn't considering that at all since I had yet to see it written anywhere.

[labarba]

Clearly we need to improve the author guide, but we do say:

Computational learning modules should be complete and immediately usable for self-learning or adoption by other instructors. They should make a clear contribution to teaching and learning of any subject, supported by computing.

[moorepants]

Here is a summary of what I'm understanding at this point, which adds three new points to the two that were already on the JOSE website:

• Primary materials should be able to be used by a self-learner and optionally an instructor.
• Primary materials must be created from an open format plain-text based source to maximize technical ease of reusing and remixing.
• Primary materials must contain or use code, leaning towards "learning by coding" versus "learning to code".
• Non plain-text but open format materials can be added as supplementary materials.
• All materials should be openly licensed and openly accessible.

Does this match what you all are saying?

[moorepants]

but we do say

Sorry must have missed it.

[moorepants]

I was just checking out this very recently published JOSE paper: openjournals/jose-reviews#13

As far as I can tell the primary content is a set of slide decks. The slides are written in directly in HTML. The slides have notes for the instructor and there is a Youtube video for each module. I'd argue that without the Youtube videos, this isn't fundamentally different that the slidedeck + (yet to be written) instructor notes + R script that I've proposed here. The main difference is the author wrote their slides in HTML whereas I wrote mine in G-Slides. A self learner could probably make do with the reproducible research slides + reading the instructor notes, but that content alone isn't designed for self learning (not sure if any slide deck ever is, even with instructor notes). It is the Youtube videos paired with the slide decks that make it more realistically setup for self-learning.

So, if my slides are written in HTML instead of G-slides, would it then qualify? Or would G-slides + a Youtube video qualify? Or Impress-slides + Youtube video?

Sorry to pick at this[1], but as you may ascertain I'd prefer JOSE to only require:

Primary materials must be created in an open, non-proprietary format to maximize technical ease of reusing and remixing

over

Primary materials must be created from an open format plain-text based source to maximize technical ease of reusing and remixing

Regardless of what JOSE submission guidelines are or will be, I would like the ambiguity be lessened. Then I, and others, can adapt materials to fit whatever the consensus is.

[1] This stems from my many years of creating slide decks from text based tools (Beamer, Jupyter, Rise, Markdown, HTML, etc) and from WSYSWIG tools (Impress, G-Slides, etc). I find that the former takes loads more time for little to no gain and is actually far worse for remix/reuse because it is so hard to collaborate (not because you can't collab on text based stuff, but because the overhead of the tooling is so high, few teachers are willing to collaborate, only the most technically adept will).

[labarba]

Pull up the slides and hit "p." You'll find a full narrative (transcript).

The slides are written in markdown and are rendered using the remark framework.

[moorepants]

I saw the narratives. I called them "instructor notes" in the above comment. I would plan to submit the same with this slide deck, as mentioned above.

I now see that the .html files are actually markdown: https://github.com/riffomonas/reproducible_research/blob/gh-pages/_reproducible_research/06_organization.html. Thanks for pointing that out. That changes my above question to:

So, if my slides are written in Markdown instead of G-slides, would it then qualify? Or would G-slides + a Youtube video qualify? Or Impress-slides + Youtube video?

[labarba]

At this point, I believe it is more constructive to move the conversation to an editorial-board telecon.

I am disinclined to call materials that are solely on slides a "learning module," and publish them on JOSE. To be honest, I was ambivalent about the "Riffomonas" submission when it came in, but I relented because of the sheer size of the effort, the fact that the slides are themselves "reproducible" and fully annotated, and the endorsement of @tracykteal who knew the effort.

One issue is that we do want to promote the development of materials that are reusable (as I said) for both instructors and learners. Another is that we want to promote sound pedagogical practices. I have rarely (if ever) seen solid pedagogy demonstrated on slide-based teaching.

As EiC, I want JOSE to encourage more instructors to write stand-alone narratives that embed computation, and that are closer to executable textbooks (or textbook chapters) than the MIT flavor of open courseware (which has very little reuse).

[moorepants]

I'd be happy to chat via telephone about this. Although, there are two issues I'm discussing here that are mixed together. Maybe only one warrants a larger discussion. The first 1) is "can we lessen the ambiguity in the currently defined submission criteria?" and the second 2) is "can we relax the plain-text source requirement for the materials?" I can move 2) to another issue and discuss over telecon, or at a future meeting, etc. No rush needed. But for 1) I'd like to make a PR to the "about" page to clarify some of the language around the submission criteria that can help with openjournals/jose-old#21, openjournals/jose-old#20, and openjournals/jose-old#6. My proposal would be to add a checklist of this flavor:

• [] Primary materials should be able to be used by a self-learner and by an instructor.
• [] Primary materials must be created from an open format plain-text based source to maximize technical ease of reusing and remixing.
• [] Primary materials must contain or use code, leaning towards "learning by coding" versus "learning to code".
• [] Non plain-text but open format materials can be added as supplementary materials.
• [] All materials should be openly licensed and openly accessible.

And to make the existing text align with this and be consistent. If this seems reasonable, I can open a PR and move the discussion about that there. I think that it essentially reflects the current guidelines.

[labarba]

I agree with the items you list above.

You previously noted that making slides on plain-text frameworks is more time-consuming, even painful, and may result in poorer quality. I agree! Google slides is easier and can be done well (if you have some sense of design and avoid the ugly defaults). But how do you export those slides outside Google Drive, into some format that can be archived, and maintains the editing features? I haven't looked into that—I just didn't consider that we'd be publishing slides on JOSE.

I'm not firm on requiring plain-text source, and other open formats could be OK (but they need to be able to be archived in a proper repository). What I really disapprove of, in general, is publishing slide-based content.

[moorepants]

I agree with the items you list above.

Great. I'll work on a PR wrt to this.

As for the other two paragraphs, it is something worth discussing further. I'm very much against "death by powerpoint"-teaching but I think there is an effective role for slides in teaching. I similarly see Juptyer notebooks having an effective role in teaching even though they also have many of same qualities that teachers abuse/overuse with slide decks.

I'll open another issue about the type of materials we can accept, which can be tied to a phone call, meeting, etc, in the future. Thanks for hearing me out.