Find and/or build tools to help manage lesson material.

[gvwilson]

Our lesson materials are written in a variety of formats, including HTML, plain Markdown, IPython Notebooks, and R Markdown. What tools can we find and/or build to help manage this? Some of the issues we need to consider are:

• make it really simple for instructors to get set up for creating and previewing lessons
• consistent appearance
• simple inter-linking
• incorporating lessons into the main web site

See also: #120 (metadata)

[wking]

On Sat, Nov 02, 2013 at 08:37:49AM -0700, Greg Wilson wrote:

• incorporating lessons into the main web site

From the FAQ 1:

We will usually give permission to any training that covers the four
basic topic areas of structured programming, task automation,
version control, and testing,…

Developing standard, tool-specific curricula (#118) makes sense, but I
think that binding SWC and it's tool-agnostic goals too tightly to a
particular toolset or lesson implementation distracts from the larger
vision. That makes me leary of incorperating a particular lesson
collection in the main site (although I realize I just floated that
possibility here 2 ;). I'd rather see links out to a handful of
affiliated lesson/boot-camp sites, and I don't have a preference about
where those sites are hosted.

[ahmadia]

@wking - I'm not sure this is the right thread to discuss broader organization strategies. I also don't think that discussion is going to be open again for another couple of months while we try and knuckle out the reorganization strategy targeted by @gvwilson for the end of this year.

[gvwilson]

Jonathan Frederic and Matthias Bussonier (from the core IPython dev team) built a couple of widgets for the Notebook that will allow us to tag cells with keywords (like 'instructor', 'student', 'pointform', 'prose'), and then run that notebook through nbconvert to produce a new notebook containing only the cells that pass certain Boolean criteria (e.g., only have cells marked 'student AND pointform'). See http://elacave.lmdb.eu/~carreau/SWC-tags.mov for a video, and https://github.com/jdfreder/notebook_cherry_picker/ for the cherry-picker. Can we use this to keep multiple content in a single file (which aids consistency management) while also generating what we want to have for different audiences? If so, what's the equivalent for plain Markdown, R Markdown, and other formats?

[ethanwhite]

Jonathan Frederic and Matthias Bussonier (from the core IPython dev team) built a couple of widgets for the Notebook that will allow us to tag cells with keywords (like 'instructor', 'student', 'pointform', 'prose'), and then run that notebook through nbconvert to produce a new notebook containing only the cells that pass certain Boolean criteria (e.g., only have cells marked 'student AND pointform').

This is an awesome idea that clearly has implications beyond SWC. I'll certainly be using these tools for my university courses when we're doing Python. I think this is something that could be so useful it might be worth solving ourselves for Markdown/RMarkdown if it doesn't already exist. Since we're simply subsetting I suspect that it would just be a single Markdown tool that would also work with RMarkdown. Presumably it would use html comments to do the tagging.

[rgaiacs]

@gvwilson Nice tool.

I know that Sphinx have a extension for something like that.

For Markdown the easy way should be using CSS display:none; property.

[wking]

On Sun, Nov 03, 2013 at 09:34:01AM -0800, r-gaia-cs wrote:

For Markdown the easy way should be using CSS display:none;
property.

That means tags in the Markdown source:

$ cat some-lesson.md
<div class="instructor pointform">

…

</div>

<div class="student prose">

…

</div>

with appropriate style-sheets:

$ cat student-pointform.css
.instructor .prose {
  display: none;
}

That won't be too bad to write, but it might confuse students reading
the source directly. I expect you'd have to write a parser (shouldn't
be too complicated) to create subset-Markdown source if you wanted
students to be able to follow along in their pager/editor (vs. their
browser).

[wking]

On Sun, Nov 03, 2013 at 10:01:55AM -0800, W. Trevor King wrote:

That won't be too bad to write, …

But it also wouldn't be all that different from just writing separate
Markdown files for point-form instructor and prose student passes
through the same material. I expect folks will be using two editor
panes either way while they work on their update.

[ahmadia]

@gvwilson:

Can we use this to keep multiple content in a single file (which aids consistency management) while also generating what we want to have for different audiences? If so, what's the equivalent for plain Markdown, R Markdown, and other formats?

The technology for managing this is relatively simple, since the notebooks are highly formatted JSON with fields for additional metadata cells. The biggest hurdles come in implementing the Javascript widgets that simplify editing from the web browser.

I think you're asking two questions here.

1] Is an IPython Notebook solution sufficient for maintaining many different proto-forms of material under version control that is still easy to manage, split into subcomponent notebooks, and present?

2] Are there equivalent tools in other formats that would allow us to do the same?

@wking brings up <divs>, which have explicit opening and closing blocks. If we are already committed to organizing using IPython Notebooks plus Metadata, I would also suggest that we use IPython Notebooks as our version controlled proto-Markdown. We would then run an intermediate tool like nbconvert (now included in IPython) to convert the notebook from instructor edit form to presentation ready form.

I'm going to copy and paste this response into #120, since the answer to "Can we do this technically without too much distractive mental burden on our content writers?" is certainly "Yes", whereas the deeper question of "Do we want to commit to this format?" belongs in #120.

[gvwilson]

PR #118 now includes some beginner Python lessons in notebook form, along with some questions to help focus discussion. Please keep the discussion going here rather than there: those notebooks are intended primarily as a straw man.

[twitwi]

If we consider the slides ("powerpoint" presentations) as part of the lesson material then I would recommend going for a web based alternative. I would especially recommend deck.js.

The advantages of web presentation I can see:

• over powerpoint, keynote, ...: easy version control
• over latex: easy edition and styling, easy integration of any kind of media, animations, direct inclusion of ipython notebook in slides, ...

[ahmadia]

@twitwi - Thanks for your thoughts on this.

I don't think Powerpoint, Keynote, or LaTeX are on the table as options. We may consider deck.js later as a web presentation format, I will be sure to ping you when we reach that part of the conversation :)

For now, I am more interested in understanding what the core structure of our lesson content will be, and that conversation is happening in #120.

[gvwilson]

See #167 for a PR that needs help with tooling: how do we nest Markdown inside HTML when we're using Jekyll as our processor, or do we need to use HTML whenever we're in HTML, or can we use something other than a <div> for denoting regions containing objectives, key points, and exercises?

[gvwilson]

"Closed" by #347 (as in, that's what we're going with for now).