What structure and metadata should lessons have?

[gvwilson]

This issue is for discussion of issues around structure and metadata, including:

• What metadata should we put in lessons to make material findable?
• Where should that live? In the lesson materials, in README files, ...?
• More generally, what structure should lessons in various formats have? What files should lesson directories include, where should data files go, what title/sub-title conventions should we use, ...?

See also: #119 (tooling)

[ethanwhite]

A plug for long-form lecture notes for our core lesson material

• Long-form notes make life easy for beginning instructors. You don't have to
  come up with your own exercises, it's less necessary to think on your feet,
  and if you get lost you can fall back to basically reading the notes.
• People like to teach in lots of different ways with different kinds of base
  material. It should be easier to treat/transform long-form notes into shorter
  form notes than the other way around. For example, you could either highlight
  the core points in the notes or delete the pieces you don't want in your notes
  before printing them.
• It's easier to use long-form notes as web-based material, either for reviewing
  after a bootcamp or for folks who want to learn on their own from the web.
• My impression is that the majority of the current material in the bc repo is
  long-form notes making it an easier starting point.

[wking]

On Sat, Nov 02, 2013 at 03:39:21PM -0700, Ethan White wrote:

• People like to teach in lots of different ways with different
  kinds of base material. It should be easier to treat/transform
  long-form notes into shorter form notes than the other way
  around. For example, you could either highlight the core points in
  the notes or delete the pieces you don't want in your notes before
  printing them.

I'm not personally insterested in long form note, but I'm not against
having them. I do think that short form instructor notes are useful
regardless of whether or not long form notes exist. Points for
short-form notes:

• Instructors with different teaching styles or formatting preferences
  (e.g. Markdown vs. ReST) can still agree on short form notes.
• Short-form notes are exclusively instructor-facing, so you can add
  notes that an instructor would find useful, but that a student might
  find confusing or distracting (common pitfalls, gotchas, exposition
  hints, figure sources, fallback material, …).
• It's easier to skim short form notes to get a feel for the lesson,
  and decide if you're even interested in the long-form version.

We obviously want to start with what we've already got, but I think
maintaining parallel short-form notes is definately worth the effort.

[wking]

On Sat, Nov 02, 2013 at 04:00:47PM -0700, W. Trevor King wrote:

I do think that short form instructor notes are useful regardless of
whether or not long form notes exist.

But this doesn't really matter. We've got maintainers now, and lots
of prior art to choose from. Pick something you like the feel of,
float it in a PR, weight our feedback, and then decide if it gets
merged, rerolled, or dropped. If you end up with long-form only
notes, I'll try to talk you into accepting short-form versions as
well, but that's down the road a few PRs. I doubt we're going to
change each-others minds in an abstract argument, and non-maintainers
can't start advocating for changes and compromises until we have
something more concrete to talk about (pointers to existing concrete
stuff you're leaning towards would be great :).

[jiffyclub]

For a little context, the development we're talking about here is focused solely on in-classroom, boot camp lessons. Self-guided content for the SWC website is going to take remain on the back burner for now.

With that in mind it's clear that instructors are as much the audience for this material as students. In fact, I think instructors are the primary audience of this material. It's here to tell instructors, "if you have the goal of teaching X, these talking points cover the necessary concepts and these exercises provide students the necessary practice".

We, the lesson writers, are a step removed from the students. We only speak directly to other instructors. Let's keep that in mind as we organize and create the lesson material.

[jiffyclub]

In response to @ethanwhite, I think "long-form notes" is a good idea, but we can be more specific. When I think of my ideal material I think it should have notes for instructors that are sufficiently detailed as to contain a brief description of every step of the lesson. Not the actual words to say, but a reminder of what's being covered at every point. The instructor notes for ipythonblocks are a good example of what I like to have. These are really useful for getting back on track after answering student questions and making sure you don't accidentally skip over important points.

[jiffyclub]

We also need to think about improving discoverability and browsability of the lessons, possibly in conjunction with #119. For example, do we want lesson directories to contain a special metadata file or header that some tool can use to generate an index?

We should also have a file or header for humans that describes the lessons content. What is the goal of the lesson? What prior knowledge does it require? The starting point and end point and relation to any other lessons. How long does it take and what extra things (e.g. ipythonblocks) does it use?

[ethanwhite]

I doubt we're going to change each-others minds in an abstract
argument

Actually, I'm totally open to any of the possible approaches here.
@gvwilson asked us to have a conversation about this so I was just
getting it started with my initial perspective. The most important thing
from my perspective is that we reach a consensus on what we're trying
to do so that we invest our limited time and energy towards a cohesive
set of material that maximally benefits SWC learners and instructors.
I'd personally much rather do this before we put a bunch of effort into
material.

We've got maintainers now, and lots of prior art to choose from.
Pick something you like the feel of, float it in a PR, weight our
feedback, and then decide if it gets merged, rerolled, or dropped.

I'm not personally comfortable with the "maintainer" label that you've
started applying to folks. I know that it makes sense for some open
source projects, but I don't think it really applies here. Greg asked
me to invest some time in helping coordinate and drive the
intermediate material forward and I'm happy to do so, but I haven't
been imbued with any hierarchical decision making power and don't
intend on exercising any. I think as a community we've been doing a
great job of reaching fairly broad consensus on things and if we can't
then Greg should make the final call.

pointers to existing concrete stuff you're leaning towards would be
great :).

In response to @ethanwhite, I think "long-form notes" is a good
idea, but we can be more specific.

Here are a couple of examples of the kind of notes I use when
developing material and teaching in bootcamps:

https://github.com/ethanwhite/swc-bootcamp-material/blob/master/Lectures/sql.md
https://github.com/ethanwhite/swc-bootcamp-material/blob/master/Lectures/shell.md

I like having the actual language I'm going to use fleshed out because
I find it helpful to read through the language when preparing the
night (or morning) before the lecture. It shortens the amount of time
I need to spend preparing. In general I find that it is possible to
say things more clearly and concisely by writing and revising and I
find this particularly valuable in a bootcamp context where time is so
limiting.

[wking]

On Sat, Nov 02, 2013 at 08:01:31PM -0700, Ethan White wrote:

The most important thing from my perspective is that we reach a
consensus on what we're trying to do so that we invest our limited
time and energy towards a cohesive set of material that maximally
benefits SWC learners and instructors.

I think the starting point is just selecting from the myriad of
existing SWC-connected lessons, since lots of folks have already sunk
a good deal of time into writing content in many flavors.

We've got maintainers now, and lots of prior art to choose from.
Pick something you like the feel of, float it in a PR, weight our
feedback, and then decide if it gets merged, rerolled, or dropped.

I'm not personally comfortable with the "maintainer" label that
you've started applying to folks.

If we want to use a different label, I'm open to that. Development in
swcarpentry/boot-camps was slow, with most instructors branching off
in their own directions (#117). Development in swcarpentry/bc has
been fast, with all sorts of things coming in (#106). It's hard to be
all things to all instructors, and I think having someone in an
editorial role culling repository is important. If we end up with
parallel lesson sets (novice, intermediate, @wking, …), that's fine.
If we end up with a backwater or kitchen sink, that's not very
helpful.

https://github.com/ethanwhite/swc-bootcamp-material/blob/master/Lectures/shell.md

This looks good to me. It's much more narrowly scoped than the
hacker-within material 1. I think that's a good thing. The
distinction between absolute and relative paths is important, but not
in your first two days of “welcome to software”.

I'd rather not have binary ODT files in the repository, though.

I like having the actual language I'm going to use fleshed out
because I find it helpful to read through the language when
preparing the night (or morning) before the lecture. It shortens the
amount of time I need to spend preparing. In general I find that it
is possible to say things more clearly and concisely by writing and
revising and I find this particularly valuable in a bootcamp context
where time is so limiting.

That makes sense, I'm just not sure how well your language translates
for other instructors. If it turns out that folks like teaching from
this more than they like teaching from short-form notes, then great.
It would be nice if recent shell instructors could chime in on whether
they've been:

• Using their own long-form notes
• Using their own short-form outline
• Using someone else's short-form outline
• Using someone else's long-form notes
• Something else?

And let us know what they'd like to see out of this centralized
effort.

[ahmadia]

I'm copying over my response to @gvwilson's question in #119 because I think it is more relevant here. Apologies for the noise if this isn't on-topic.

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.

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

[ahmadia]

@gvwilson - I don't have any substantial feedback on the notebooks aside from the fact that they are absolutely beautiful. I really wish there was material around like this when I was learning Python.

I notice that you're not using any metadata and the format is basically longform, without instructor's notes or exercises. Additionally, the notebooks are "heavy", that is, the sometimes-binary output is being stored in addition to the notebooks. This is more commentary than criticism.

• NB 1
• NB 2
• NB 3
• NB 4

[jiffyclub]

@gvwilson 's lessons are good lessons, but they are really written for students. In fact, an instructor doesn't even need to be involved for these, they'd make great reference material for the web. I especially like the 4th one. 😸

In a boot camp there's not much point to giving students reading material, they're going to be listening to the instructor. These notebooks are really too dense to be used as lecture notes and where are the exercises for students?

I personally like to work in a blank notebook and have students do the same. If we do start using the cell metadata tool mentioned in #119 then notebooks like this might be a good way to design lessons. Some cells could go to instructor notes, some cells could go to exercises, some to exercise solutions, and others to a narrative notebook that can be posted online.

But there are still potential conflicts between the goals of narrative notebooks and classroom lessons. Pacing and time come first to mind. In a narrative we are targeting someone reading, and people can read much faster than they can speak.

[jiffyclub]

@gvwilson : This is a side note, but the first challenge set in 01-numpy.ipynb seems utterly unrelated to the preceding material.

[gvwilson]

On 2013-11-03 11:30 PM, Matt Davis wrote:

@gvwilson https://github.com/gvwilson : This is a side note, but the
first challenge set in 01-numpy.ipynb seems utterly unrelated to the
preceding material.

That's not a side note at all, that's good feedback :-) I'll fix...

[ethanwhite]

Not surprisingly given my earlier comments I like the general style of @gvwilson's examples. I do think there are some things in them that could be improved if we decided to go this route. Specifically I agree with @jiffyclub that in some places

These notebooks are really too dense to be used as lecture notes

However, I think of this as being an issue specific to these particular notes (and only in a few spots), whereas it is my impression that Matt views it as a more general issue with the format. Specifically I don't agree that

there are still potential conflicts between the goals of narrative notebooks and classroom lessons. Pacing and time come first to mind. In a narrative we are targeting someone reading, and people can read much faster than they can speak.

Pacing and time are simply a question of thinking about what goes into long-form notes properly. It may be tempting to include more information than can fit into a n hour block, and we would need to be careful to avoid this, but it certainly doesn't have to be the case. For example, the notes I linked to earlier in the discussion are all presented live in 2-3 hour blocks. In fact, I think that proper pacing and time are one of the strengths of long-form notes because these can be worked out and formally recorded in the form of the content of the notes such that different instructors (or the same instructor 2 months later) can deliver the same material in the same period of time. In contrast, different people with the same set of short-form notes of the key topics to cover can end up going very different lengths of time through different levels of detail and different asides. In my experience watching both university professors and SWC instructors this tends to lead to getting less far in the material than desired due to taking too long in early material.

In a boot camp there's not much point to giving students reading material, they're going to be listening to the instructor.

I personally like to work in a blank notebook and have students do the same.

I agree completely with this and in fact I think providing anything other than cheat sheets during the bootcamp is counterproductive, but I think this is separate from long-form vs. short-form notes. They seem related because in concept we could provide the long-form notes directly to the students, but it's really a separate decision of whether or not to provide notes to them.

In fact, an instructor doesn't even need to be involved for these, they'd make great reference material for the web.

While this isn't a goal of the current discussion I do think that if the note format has the added benefit of also working online it's actually a good thing.

Finally, I'd like to note something really interesting about these notes, which is the use of a underlying example that can easily be translated to different disciplines. By focusing on a simple time-series (a type of data common to most disciplines) it makes swapping in a different discipline specific example really easy. It would be a good exercise to think up general types of data that are common across disciplines so that instructors can basically change the labels to customize the notes to the discipline of the bootcamp.

[gvwilson]

On 2013-11-03 11:29 PM, Matt Davis wrote:

@gvwilson https://github.com/gvwilson 's lessons are good lessons,
but they are really written for students. In fact, an instructor
doesn't even need to be involved for these, they'd make great
reference material for the web. I especially like the 4th one.

Thanks --- if we agree on the long-form, we can add point-form and then
extract using the yet-to-be-written tag-and-extract tool to create
notebooks for students.

In a boot camp there's not much point to giving students reading
material, they're going to be listening to the instructor. These
notebooks are really too dense to be used as lecture notes and where
are the exercises for students?

Notebooks 1-4 have (some) challenges embedded; notebooks 5-6 will get
them today.

I personally like to work in a blank notebook and have students do the
same.

That's how I teach too --- I hope this gives instructors an idea of what
to say when.
Thx,
G

[jiffyclub]

I just like to have material that is actually directed at me. The notebooks @gvwilson has put together are like a script for a play without the stage directions. When students attempt a certain exercise, what issues are likely to be their stumbling blocks? What holes are they likely to have dug for themselves (this happens in Git all the time)? When should I introduce concept X or circle back to concept Y? Those are the kind of notes I put into my printed lecture materials. Warnings like "this next thing introduces comparison operators, be sure to say something about that so no one is surprised". Or a note like "looping over a file is like looping over a BlockGrid, be sure to draw that comparison".

[gvwilson]

On 2013-11-06 1:41 PM, Matt Davis wrote:

I just like to have material that is actually directed at /me/. The
notebooks @gvwilson https://github.com/gvwilson has put together are
like a script for a play without the stage directions. When students
attempt a certain exercise, what issues are likely to be their
stumbling blocks? What holes are they likely to have dug for
themselves (this happens in Git all the time)? When should I introduce
concept X or circle back to concept Y? Those are the kind of notes I
put into my printed lecture materials. Warnings like "this next thing
introduces comparison operators, be sure to say something about that
so no one is surprised". Or a note like "looping over a file is like
looping over a BlockGrid, be sure to draw that comparison".

+1 to instructors' notes. What format should they take in different
media? Tag the cell in the .ipynb, use a div with a particular class in
a Markdown file, something else? (I used div's in the Markdown stuff in
_includes so that we could find/style it more easily...)

[ahmadia]

See my suggestion here. I'm voting that we use IPython Notebooks to organize our content, and tag the corresponding notebook cell with our metadata in the form of a simple dictionary:

swc_content_tags =
{
longform: True/False
instructor: True/False
highlight: True/False
}

We could then expose a series of little checkboxes for each key in swc_content_tags, and select/unselect where cells go by clicking them.

[gvwilson]

I favor tags in notebooks (provided there's a UI for adding them: -1000 to anything that requires hand-editing .ipynb files). But are we going to use notebooks for Git lessons? For the shell? For R?

[ahmadia]

@gvwilson - We wouldn't use the notebooks to teach, but that's how we'd write and organize all of our content. The notebooks can handle anything that a Markdown-formatted lesson can, and it can easily be split out into instructor notes, longform notes, and blank notebooks with nbconvert.

I'm going to shamelessly ping @fperez and @ellisonbg on this as a sanity-check.

[gvwilson]

On 2013-11-06 2:01 PM, Aron Ahmadia wrote:

@gvwilson https://github.com/gvwilson - We wouldn't use the
notebooks to teach, but that's how we'd write and organize all of our
content. The notebooks can handle anything that a Markdown-formatted
lesson can, and it can easily be split out into instructor notes,
longform notes, and blank notebooks with nbconvert.

I'm going to shamelessly ping @fperez https://github.com/fperez and
@ellisonbg https://github.com/ellisonbg on this as a sanity-check.

I think they're likely to be biased :-) What do @ethanwhite,
@jiffyclub, and a few others think? (Personally, if there's a plugin
for the notebook that will colorize cells containing copied-and-pasted
shell commands and output in a useful way, I could be sold.)

[ahmadia]

@gvwilson - Could you elaborate on what you're asking for with regards to colorized cells? Also cc-ing @wltrimbl, @jdblischak, @karthik and @wking because we're getting a bit closer to a decision here.

@jdblischak / @karthik - Can you comment on whether similar functionality exists in knitr, or whether it would be reasonable to consider IPython Notebook as the proto-format for R lessons as well. My inclination would be to continue to write R lessons in its own proto-languages like .RMd as long as it can provide similar functionality to what we're trying to get here.

[wking]

On Wed, Nov 06, 2013 at 11:01:30AM -0800, Aron Ahmadia wrote:

@gvwilson - We wouldn't use the notebooks to teach, but that's how
we'd write and organize all of our content. The notebooks can
handle anything that a Markdown-formatted lesson can, and it can
easily be split out into instructor notes, longform notes, and blank
notebooks with nbconvert.

While we could use tagged notebook cells to group different forms of
related content together, it introduces a separate compilation step
and I still 1 don't understand how it makes maintenance easier than
just mananging parallel versions in their native formats.

[gvwilson]

While we could use tagged notebook cells to group different forms of
related content together, it introduces a separate compilation step
and I still [1] don't understand how it makes maintenance easier than
just mananging parallel versions in their native formats.
Documentation in code (e.g., Javadoc, docstrings) is much more likely to
be maintained that documentation in external files. Similarly, I
strongly believe that point-form notes (for instructors or students)
that are adjacent to code/long-form explanations, in the same document,
are much more likely to be kept consistent.

[abostroem]

Ok, I just finished reading this thread, its a long one. Here are my thoughts (in no particular order):

+1 for long form notes (I don't think there is much disagreement here). My only concern is that an inexperienced instructor will put the long form notes up and basically read them to the class. I call this lesson planning. As to @wking comment about it being a novel. I've never seen an over-prepared instructor, but I've definitely seen under prepared instructors. We should be encouraging our instructors to carefully look over the material they are teaching in detail before they get in front of a class. I know from experience, that my lessons are always smoother when I've really gone over my material, not just the highlights.

+1 for including stage directions. Many of the notes you direct at an instructor, you also want to direct at students who are trying to follow the material on their own. I see these notes as notes to the instructor which double as reference material for the students.

For teaching python and testing, I think the notebook is really useful to both contain notes and teach out of. Will the final ipynb rendered notes look like a notebook? We should be sure that inexperience instructors don't teach shell in a notebook. I've confused myself this way by lesson planning a testing unit in a notebook when I planned to teach in a text editor and then starting to teach the material in a notebook. I know student's have left SWC boot camps thinking that everything happens in an ipython notebook and not knowing how to use the shell outside of it.

I'd be cautious of making our chosen lesson language too specialized. If contributors start having to learn a lot of special syntax and formatting to contribute, they may not contribute. I'm much more likely to contribute the lessons I developed if I don't have to modify them to contribute them.

I'm not sure where this falls in the discussion, but I like teaching git using a presentation + command line. How do presentations fit into this discussion? The thw notes are pretty good, but I think putting up a page of text for students to read and scrolling through it can be overwhelming and hard to follow. Likewise, command go so quickly that student can get behind really easily.

The discussion of maintainers is really interesting. In my ideal SWC world, there would be a few people employed by SWC who would go through the repositories created for each boot camp and incorporate any improvements to the materials made in that book camp.

I'm still working on how to do this effectively with student interaction, but my dream is to hand students a notebook with comments but empty cells for them to type into. Then they don't have to write notes, its all there, but they are still participating in class. The issue I always run into is that a student asks a question or I forget to move to a new cell and suddenly where I am in the notebook and the notes don't match up. For those who use a blank notebook, where do you anticipate student's taking notes or getting notes from?

+1 to common examples from a variety of disciplines so our examples don't seem like they were written for a boot camp in a different subject.

I think timing is a big issue but in no way a show stopper on long form notes. Part of defining core material for SWC should be defining a set of core material that is either taught at every boot camp or the audience already knows the material so it can be skipped. There may then be a few lessons which can be switched in and out based on audience (e.g. SQL). Lessons should be the length needed to cover the material we think should be covered. If we define this material correctly then any effort to go faster or cut material will likely end up losing students. It would be extremely helpful to instructors to have how long a given lesson should take. I think with git in particular, people often don't allow enough time to cover what needs to be covered.

[ahmadia]

@abostroem - thanks for your thoughts on this :)

Will the final ipynb rendered notes look like a notebook?

My idea is to write/develop in IPython Notebook, and to then export to whatever formats are needed from there, including longform notes, instructor notes, outlines, blank notebooks, shell scripts, web pages, and slideshows. An alternative suggestion several of the other instructors are suggestion is to use Markdown as the same proto-tool. Nobody is proposing that we force the R folks to write in our tools, since they have their own stacks :)

I'm not sure where this falls in the discussion, but I like teaching git using a presentation + command line. How do presentations fit into this discussion?

IPython Notebook has a slideshow mode that we haven't been using very heavily. @williamstein's SageMathCloud has also demonstrated synchronized IPython Notebooks over a cloud patform on the web, but I don't know if it has the features we need right now (50 students simultaneously following along, read-only access, works only over common ports) for teaching.

[jiffyclub]

@ahmadia You can share notebooks in real time in a rudimentary way, see http://penandpants.com/2013/05/08/broadcasting-ipython-notebooks/. Unfortunately I've had limited success with that. It'll either have problems with too many simultaneous requests or the local network just won't allow it.

[ahmadia]

@jiffyclub - these are real-time edits, like a Google Doc or Etherpad. We're still evaluating its readiness, and we'll probably have to do a few serious dry runs before using it in a bootcamp. Sorry, not trying to start an off-topic discussion, just describing some of the interesting things happening with the IPython Notebook.

[ellisonbg]

I think the idea of tagging notebook cells for different purposes and then having a UI that can hide/show cells with different tags is a nice idea and is very consistent with how we are thinking about the notebook.

[wking]

On Wed, Nov 06, 2013 at 07:26:04PM -0800, abostroem wrote:

The discussion of maintainers is really interesting. In my ideal SWC
world, there would be a few people employed by SWC who would go
through the repositories created for each boot camp and incorporate
any improvements to the materials made in that book camp.

I think our traditional problems with this have been discoverability
and defining “improvement”. Boot camp branches and tags were intended
to help with discoverability [1](we can only incorporate your changes
if we know they exist). Deciding if a change is an improvement or not
is more subjective, and we've seen a fair bit of divergence in the
past (#117). When the broader community is split between a handful of
possible approaches, it helps to have a single person in charge of
each section who can put their foot down, pick a direction, and move
forward. We may be moving that way with the core repository [2,
sections C through E], but @ethanwhite for example is not sold yet
3. Of course, none of this means that opinionated outliers can't go
their own way…

[gvwilson]

+1 for long form notes (I don't think there is much disagreement
here). My only concern is that an inexperienced instructor will put
the long form notes up and basically read them to the class. I call
this lesson planning.
We're putting pretty much everyone through instructor training now, so
I'm not worried about them making that mistake.
+1 for including stage directions.
+1 here as well.
I'm not sure where this falls in the discussion, but I like teaching
git using a presentation + command line. How do presentations fit into
this discussion?
Presentations are the right thing in some cases, and there are dozens of
browser-based slideshow packages out there, including ones that generate
slides from Notebooks or Markdown. (I have blogged repeatedly about the
shortcomings of text-based slideshow tools, but I agree they're a better
solution for our situation than a rich-but-opaque format.)

The discussion of maintainers is really interesting. In my ideal SWC
world, there would be a few people employed by SWC who would go
through the repositories created for each boot camp and incorporate
any improvements to the materials made in that book camp.

My ideal world includes that too --- unfortunately, my actual world
still doesn't include the budget for it. If one of you could get
yourself appointed Director of the NSF and start steering funding
towards skills training, I'd be grateful :-)

I'm still working on how to do this effectively with student
interaction, but my dream is to hand students a notebook with comments
but empty cells for them to type into. Then they don't have to write
notes, its all there, but they are still participating in class. The
issue I always run into is that a student asks a question or I forget
to move to a new cell and suddenly where I am in the notebook and the
notes don't match up. For those who use a blank notebook, where do you
anticipate student's taking notes or getting notes from?

+1 to this scaffolded approach, particularly if (some of) the cells
contain skeletal code:

numbers = [3, 5, 7, 9]
total = []
for []:
total = [____]

+1 to common examples from a variety of disciplines so our examples
don't seem like they were written for a boot camp in a different subject.

I think timing is a big issue but in no way a show stopper on long
form notes. Part of defining core material for SWC should be defining
a set of core material that is either taught at every boot camp or the
audience already knows the material so it can be skipped. There may
then be a few lessons which can be switched in and out based on
audience (e.g. SQL). Lessons should be the length needed to cover the
material we think should be covered. If we define this material
correctly then any effort to go faster or cut material will likely end
up losing students. It would be extremely helpful to instructors to
have how long a given lesson should take. I think with git in
particular, people often don't allow enough time to cover what needs
to be covered.

—
Reply to this email directly or view it on GitHub
#120 (comment).

[gvwilson]

On 2013-11-06 11:27 PM, Matt Davis wrote:

@ahmadia https://github.com/ahmadia You can share notebooks in real
time in a rudimentary way, see
http://penandpants.com/2013/05/08/broadcasting-ipython-notebooks/.
Unfortunately I've had limited success with that. It'll either have
problems with too many simultaneous requests or the local network just
won't allow it.

-1 on real-time sharing until we can be sure that university WiFi will
reliably handle the load.

[gvwilson]

+1 for long form notes (I don't think there is much disagreement
here). My only concern is that an inexperienced instructor will put
the long form notes up and basically read them to the class. I call
this lesson planning.
We're putting pretty much everyone through instructor training now, so
I'm not worried about them making that mistake.
+1 for including stage directions.
+1 here as well.
I'm not sure where this falls in the discussion, but I like teaching
git using a presentation + command line. How do presentations fit into
this discussion?
Presentations are the right thing in some cases, and there are dozens of
browser-based slideshow packages out there, including ones that generate
slides from Notebooks or Markdown. (I have blogged repeatedly about the
shortcomings of text-based slideshow tools, but I agree they're a better
solution for our situation than a rich-but-opaque format.)

The discussion of maintainers is really interesting. In my ideal SWC
world, there would be a few people employed by SWC who would go
through the repositories created for each boot camp and incorporate
any improvements to the materials made in that book camp.

My ideal world includes that too --- unfortunately, my actual world
still doesn't include the budget for it. If one of you could get
yourself appointed Director of the NSF and start steering funding
towards skills training, I'd be grateful :-)

I'm still working on how to do this effectively with student
interaction, but my dream is to hand students a notebook with comments
but empty cells for them to type into. Then they don't have to write
notes, its all there, but they are still participating in class. The
issue I always run into is that a student asks a question or I forget
to move to a new cell and suddenly where I am in the notebook and the
notes don't match up. For those who use a blank notebook, where do you
anticipate student's taking notes or getting notes from?

+1 to this scaffolded approach, particularly if (some of) the cells
contain skeletal code:

numbers = [3, 5, 7, 9]
total = []
for []:
total = [____]
print 'sum of values in list:', total

+1 to common examples from a variety of disciplines so our examples
don't seem like they were written for a boot camp in a different subject.

Contributions toward this would be very welcome.

[wking]

On Thu, Nov 07, 2013 at 09:14:50AM -0800, Greg Wilson wrote:

The discussion of maintainers is really interesting. In my ideal SWC
world, there would be a few people employed by SWC who would go
through the repositories created for each boot camp and incorporate
any improvements to the materials made in that book camp.

My ideal world includes that too --- unfortunately, my actual world
still doesn't include the budget for it. If one of you could get
yourself appointed Director of the NSF and start steering funding
towards skills training, I'd be grateful :-)

While a few people handling all of SWC's lesson content would probably
need some supporting funding, I don't see why we can't split this into
a lot of tiny jobs that folks can handle on a volunteer basis. My
per-lesson-branch approach in #102 was designed to make each lesson a
separate fiefdom with it's own maintainer in charge of integrating
per-boot-camp improvements (as they personally define “improvements”).
With per-boot-camp tagging of some sort for discoverability, I don't
think merging per-boot-camp improvements to your single lesson would
be too much work for someone who can spare a few hours a month. With
clearer lesson-maintainer positions, it's also possible that boot-camp
instructors would get more proactive about pushing improvements back
upstream, which would make maintaining individual lessons much easier.

[bendmorris]

First, I would prefer to use Markdown instead of IPython notebooks for notes, whether they're intended for instructors or students. I like working with IPython notebooks during a bootcamp but not preparing from them, because I can read the Markdown right here on github but I have to clone the repo and fire up the notebook to use it locally. Also, I usually conclude bootcamps by showing the SWC github repositories to the students as a self-learning resource and suggesting that anyone interested could become an instructor or contributor as well. I'd like the material on here to be as accessible to them as possible, and if they haven't seen them before (either it's an R-focused bootcamp, we taught without notebooks, they weren't paying attention during the Python portions, etc.) then notebooks are another barrier between it and them. I agree with @karthik and @emhart on this.

Second, it's not like we're running out of space on github - does there need to be a canonical version of lesson plans and their notes? Can we provide notes with different narratives, examples, problems, orderings, skill levels, etc. and let people use what they find helpful? When I'm preparing to teach, I almost never print off a single resource and use it as a script - instead, I'll spend a few hours going through several different versions and selecting out parts I like and think are relevant to the group, and forming my own narrative. I produce something like @ethanwhite's notes whenever I first teach something, and I iteratively change them based on my experiences with them and the audience. People tend to have different styles and do things in different but equally valid ways when covering the same topic. I recently taught with @karthik, and he taught Git differently from how I teach it, but his presentation was very effective. At the same time, I probably won't be changing how I teach it because it has also been effective. Neither is really an "improvement" of the other. Someone might read my lesson plan and Karthik's and come up with their own that's a cross between the two, or they might decide that his is more suitable for their audience and go with that one. Providing multiple takes can be helpful.

[wking]

On Thu, Nov 07, 2013 at 09:27:33AM -0800, Ben Morris wrote:

People tend to have different styles and do things in different but
equally valid ways when covering the same topic.

+1, and another reason for good per-lesson discoverability and
swap-ability.

[ahmadia]

@bendmorris - Thanks for joining the discussion and raising several important points. I like your points about teaching from notebooks but reading from Markdown. I agree that any solution we use needs reasonable integration with tools like GitHub. I'm not sure I'm willing to make the trade of versioning our lesson content in formatted files for raw Markdown, though. The Notebook JSON is not as pretty as Markdown, but it's still readable in a text diff, and it is easier to be parsed and used by our own tools.

Second, it's not like we're running out of space on github - does there need to be a canonical version of lesson plans and their notes? Can we provide notes with different narratives, examples, problems, orderings, skill levels, etc. and let people use what they find helpful? When I'm preparing to teach, I almost never print off a single resource and use it as a script - instead, I'll spend a few hours going through several different versions and selecting out parts I like and think are relevant to the group, and forming my own narrative.

We're definitely trying to build and maintain high-quality core content. The current focus is on that. Having many copies of lesson content has made it difficult for instructors to pick a curriculum. I'm happy to host a repository of all content people have taught with in the past, but the additional tightening on "Software Carpentry" the brand means that we can no longer host unreviewed content under the swcarpentry organization.

@wking - Sorry, but I think we need to table discussion on per-lesson branches/swappability in this thread. It's a great idea for the long term, but we're dealing with enough other issues in this thread at this point that it's distracting from the discussion.

[gvwilson]

Given comments to date, I'd like to propose the following:

1. Each Python lesson is stored in a single notebook (but the novice and intermediate lessons are in separate notebooks).
2. Each notebook contains long-form prose, notes for learners, and notes for instructors as well as code.
3. Cells in these notebook are tagged using https://github.com/jdfreder/notebook_cherry_picker (I'll propose a very small set of tags in a separate message).
4. We run these notebooks through nbconvert to construct the notebooks that will be given to learners as a starting point in class, used by the instructor in class, read by the instructor before class to prepare, etc.

If everyone agrees to this, we can start constructing the new novice and intermediate Python lessons, and continue this discussion to decide:

• what we do about things like R that have their own preferred formats, and
• what we do about things like the shell that don't (i.e., things where we could use notebooks, plain Markdown files, or something as yet undecided).

Please vote +1, -1, or 0 so we can see where we are.

[ahmadia]

+1 to @gvwilson's proposal.

I'd also propose a white-ballot on letting tools like R have their own preferred format, since I think we're unanimous on that as well.

Also, @gvwilson, as a small addendum to 3], there are Javascript tools that allow you to live-fold IPython Notebook cells while editing as well, and we should be able to add some tools that simplify that sort of editing as well.

[jiffyclub]

I'm +1 on @gvwilson points, was about to posit the same stuff. I was going to go so far as to say that we should go ahead and agree on an analogous system using Markdown for shell and Git.

I'd also expand the guidelines to say explicitly that the base format of lessons should be tutorials and solved exercises directed at the students such that they could be used for learning outside of boot camps. On top of that we'll include things like instructor notes to the degree possible by our metadata hooks.

[ahmadia]

@jiffyclub - @gvwilson has correctly summarized the discussion. I'm against versioning lessons using Git and Shell with raw Markdown, so we're not in agreement on that yet (though I think I may be outnumbered). Everybody agrees that we should be using IPython Notebook and that we'd like to have multiple forms (instructor notes, longform, exercises) available within one lesson.

[jiffyclub]

@ahmadia Did I say Greg incorrectly summarized the discussion? I'm confused.

[ahmadia]

Sorry for the noise @jiffyclub - I was trying to say that we're unanimous on Python format, but not on Shell/Git, so it's better to move forward on Python and table the discussion on Shell and Git for now.

[emhart]

1. +1
2. +1
3. +1
4. 0

On Thu, Nov 7, 2013 at 11:16 AM, Greg Wilson notifications@github.comwrote:

Given comments to date, I'd like to propose the following:

1. Each Python lesson is stored in a single notebook (but the novice
   and intermediate lessons are in separate notebooks).
2. Each notebook contains long-form prose, notes for learners, and
   notes for instructors as well as code.
3. Cells in these notebook are tagged using
   https://github.com/jdfreder/notebook_cherry_picker (I'll propose a
   very small set of tags in a separate message).
4. We run these notebooks through nbconvert to construct the notebooks
   that will be given to learners as a starting point in class, used by the
   instructor in class, read by the instructor before class to prepare, etc.

If everyone agrees to this, we can start constructing the new novice and
intermediate Python lessons, and continue this discussion to decide:

• what we do about things like R that have their own preferred
  formats, and
• what we do about things like the shell that don't (i.e., things
  where we could use notebooks, plain Markdown files, or something as yet
  undecided).

Please vote +1, -1, or 0 so we can see where we are.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/120#issuecomment-27991547
.

Edmund M. Hart, PhD
Staff Scientist - Ecoinformatics
National Ecological Observatory Network
@distribecology
http://emhart.github.com

[ethanwhite]

+1 on @gvwilson's proposal.

[wking]

On Thu, Nov 07, 2013 at 10:16:21AM -0800, Greg Wilson wrote:

1. Each Python lesson is stored in a single notebook (but the novice
   and intermediate lessons are in separate notebooks).

-0, but if I can extract the instructor notes automatically I'm
satisfied.

1. Each notebook contains long-form prose, notes for learners, and
   notes for instructors as well as code.

+1. So long as “notes for instructors” are included I'm happy.

1. Cells in these notebook are tagged…
2. We run these notebooks through nbconvert…

+0, I don't really care about the tooling.

[karthik]

+1 all around.

[gvwilson]

Can we provide notes with different narratives, examples, problems,
orderings, skill levels, etc. and let people use what they find helpful?

It depends on which "can" you have in mind. Is it physically possible?
Absolutely. Do we have the resources to create and maintain it?
Unfortunately not. I hope that once this re-org is done, and more of
our instructors are comfortable enough with GitHub to start patching
things, we'll be able to take that on, but realistically, that's at
least a year away.

[wltrimbl]

Concerning @bendmorris's comment: "it's not like we're running out of space on github" :
It's space in the instructors' minds that's at a premium. Neither high-level goal of discoverability or improvement is served by having unwieldy materials.

1. +1
2. +1
3. & 4. 0 I don't care about tooling

[gvwilson]

Thanks for your votes, everyone: motion passed. Next steps:

1. I'll put together a message for 'discuss' summarizing what's been agreed so far.
2. I'll put together a small set of tags and submit them as a PR for separate discussion (see What tags should we use for lessons content? #134).
3. Someone will volunteer to make a very short screencast showing people how to use @jdfreder's Notebook cherry picker.

Please continue the discussion here about formats for other lesson materials (for R, the shell, Git, etc.), and thanks again.

[gvwilson]

"Closed" (for now) by #347.