<div dir="ltr"><div><div><div>Hey guys,<br><br></div>I'm not looking to get into another huge debate at this juncture, but nonsequential notebooks with branching are a natural fit for different treatments or views of the same or related content, of which this is a special case. (greg and Software carpentry see <a href="http://python.6.x6.nabble.com/Some-new-cell-types-for-describing-data-analyses-in-IPy-Notebook-td5023238.html">here</a> for the very long discussion we had on ipython dev about this previously).<br>
<br>In that case, you would still slice the student notebook out, but the "tagging" would be essentially automatic and the instructor would have a natural way of having access to all the content in an intelligible and executable (incl. headless/full notebook execution) format within a single notebook .<br>
<br></div>~G<br><br></div>P.S. Hope the move is going well Brian.<br></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, Jul 29, 2013 at 11:53 AM, Greg Wilson <span dir="ltr"><<a href="mailto:gvwilson@third-bit.com" target="_blank">gvwilson@third-bit.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Thanks for the feedback, Brian. Tagging each cell with one or more of<br>
"instructor's guide", "workbook", etc., and then slicing 'em to produce<br>
different notebooks sounds like a good plan to me.  Can someone tell me<br>
(a) whether the UI elements for adding tags exist yet, (b) if not,<br>
whether they're in process, (c) if not, whether they can be done as a<br>
plugin?<br>
Thanks,<br>
Greg<br>
<div class="HOEnZb"><div class="h5"><br>
On 2013-07-29 1:31 PM, Brian Granger wrote:<br>
> Greg,<br>
><br>
> Here is what I would do *today*.<br>
><br>
> * I would author a single notebook that has all of the content.<br>
> * I would use cell level metadata to add to the tags list.  At the dev<br>
> meeting we decided to add a top level tags key that is a list of tags<br>
> to the cell level metadata.<br>
> * I would write a custom Transformer for nbconvert that filters<br>
> notebook cells based on these tags.<br>
> * I would run run nbconvert multiple times to produce the different notebooks.<br>
><br>
> Sorry I am so brief - we are moving this week so I am mostly offline.<br>
> Other people can help with the details of these things.<br>
><br>
> Cheers,<br>
><br>
> Brian<br>
><br>
> On Mon, Jul 29, 2013 at 8:13 AM, Greg Wilson <<a href="mailto:gvwilson@third-bit.com">gvwilson@third-bit.com</a>> wrote:<br>
>> Hi,<br>
>> I posted the message below to the Software Carpentry discussion list a<br>
>> few minutes ago.  I'd appreciate input from the IPython Notebook<br>
>> community as well.<br>
>> Thanks,<br>
>> Greg<br>
>> p.s. if anyone has a good way to manage discussion that spans two<br>
>> independent mailing lists, I'm all ears... :-)<br>
>><br>
>> ---------------------------------------------------------------------------------------------------<br>
>><br>
>> Hi,<br>
>><br>
>> I'm trying to figure out how to satisfy four sets of needs for<br>
>> instructional material using IPython Notebooks in Software Carpentry. I<br>
>> feel like I'm thrashing, so I'd appreciate your help.<br>
>><br>
>> My four use cases are:<br>
>><br>
>> * instructor's guide: to help instructors prepare for a bootcamp<br>
>> * lecture notes: what instructors use during a bootcamp<br>
>> * workbook: what learners are given to use during a bootcamp<br>
>> * textbook: what learners use on their own outside a bootcamp<br>
>><br>
>> To make this more concrete, have a look at<br>
>> <a href="http://swcarpentry.github.io/bc/lessons/guide-shell/tutorial.html" target="_blank">http://swcarpentry.github.io/bc/lessons/guide-shell/tutorial.html</a>, which<br>
>> describes how I teach the shell:<br>
>><br>
>> *<br>
>> <a href="http://swcarpentry.github.io/bc/lessons/guide-shell/tutorial.html#s:shell:instructors" target="_blank">http://swcarpentry.github.io/bc/lessons/guide-shell/tutorial.html#s:shell:instructors</a><br>
>> is a high-level intro for instructors.  Learners might find it useful,<br>
>> but it's not really aimed at them.<br>
>><br>
>> * Each topic opens with objectives (see<br>
>> <a href="http://swcarpentry.github.io/bc/lessons/guide-shell/tutorial.html#s:shell:filedir:objectives" target="_blank">http://swcarpentry.github.io/bc/lessons/guide-shell/tutorial.html#s:shell:filedir:objectives</a><br>

>> for an example).  This belongs in the instructor's guide ("Here's what<br>
>> you're supposed to teach"), possibly the lecture notes ("Hi class,<br>
>> here's what I'm about to teach"), probably not the workbook, and<br>
>> definitely the textbook.<br>
>><br>
>> * Each topic ends with key points and challenge exercises: see<br>
>> <a href="http://swcarpentry.github.io/bc/lessons/guide-shell/tutorial.html#s:shell:filedir:keypoints" target="_blank">http://swcarpentry.github.io/bc/lessons/guide-shell/tutorial.html#s:shell:filedir:keypoints</a>,<br>

>> and<br>
>> <a href="http://swcarpentry.github.io/bc/lessons/guide-shell/tutorial.html#s:shell:filedir:challenges" target="_blank">http://swcarpentry.github.io/bc/lessons/guide-shell/tutorial.html#s:shell:filedir:challenges</a><br>

>> for examples.  Again, both belong in the instructor's guide and the<br>
>> textbook; they probably belong in the lecture notes, and probably also<br>
>> in the workbook (as a starting point for learners' own notes, and so<br>
>> that they know what to work on during practicals).<br>
>><br>
>> Problem #1: how do we manage material that ought to appear in multiple<br>
>> documents?  Right now, each snippet is a separate HTML file that is<br>
>> %include'd to assemble the entire document (see<br>
>> <a href="https://raw.github.com/swcarpentry/bc/gh-pages/lessons/guide-shell/tutorial.html" target="_blank">https://raw.github.com/swcarpentry/bc/gh-pages/lessons/guide-shell/tutorial.html</a>).<br>
>> That works OK for HTML pages, but not for notebooks: as far as I know,<br>
>> there's no way to %include file X in notebook Y.<br>
>><br>
>> Problem #2: what exactly ought to be in the lecture notes?  For example,<br>
>> compare<br>
>> <a href="http://swcarpentry.github.io/bc/lessons/guide-pyblocks/tutorial.html#s:pyblocks:logic:lesson" target="_blank">http://swcarpentry.github.io/bc/lessons/guide-pyblocks/tutorial.html#s:pyblocks:logic:lesson</a><br>

>> (the introduction to "if/else" in the incomplete instructor's guide to<br>
>> basic Python programming using IPythonBlocks) to<br>
>> <a href="http://nbviewer.ipython.org/urls/raw.github.com/swcarpentry/bc/gh-pages/lessons/guide-pyblocks/pyblocks-logic.ipynb" target="_blank">http://nbviewer.ipython.org/urls/raw.github.com/swcarpentry/bc/gh-pages/lessons/guide-pyblocks/pyblocks-logic.ipynb</a><br>

>> (an IPython Notebook with the same handful of examples).  The former is<br>
>> much too verbose to put in front of learners in a classroom setting.  I<br>
>> feel the latter is too sparse, but when I add point-form notes and then<br>
>> lecture over the result, it feels clumsy:<br>
>><br>
>> * If the item I'm currently talking about is centered on the screen,<br>
>> learners can see my next points on screen below it.  This is distracting<br>
>> --- so distracting that tools like PowerPoint and other slideshow tools<br>
>> were invented in part to prevent it happening.  If the notebook<br>
>> supported progressive reveal of pre-made cells, that problem would lessen.<br>
>><br>
>> * Even with that, though, one of the most compelling reasons to use the<br>
>> notebook as a lecture tool is lost.  Learners really like us typing code<br>
>> in as we teach: it slows us down, which makes it more likely that we'll<br>
>> walk through the code at a comprehensible pace, and it makes it a lot<br>
>> easier for us to extemporize in response to their questions or<br>
>> confusion.  We lose both benefits if we start using "reveal next",<br>
>> though we're still better off than if we use slides.<br>
>><br>
>> Problem #3: what ought to be in the workbook (the notebook we give<br>
>> students as a starting point)?  Option A is "nothing": they should type<br>
>> things in as the lecture proceeds.  This forces them to learn hands-on<br>
>> (which is good), but greatly increases the risk that they'll fall behind:<br>
>><br>
>> * They're more likely to mis-type something than the instructor, so<br>
>> their actual lines-per-second is (much) lower.<br>
>> * They want to take notes, which slows them down even further.<br>
>><br>
>> Option B is to give learners a notebook with notes and code already in<br>
>> it, but that gets us back to them (a) being distracted by material they<br>
>> haven't seen yet, but which is already on their screen, and (b) not<br>
>> having to be hands-on while learning.  On the other hand, these are<br>
>> grownups, and there's only so much we can do with existing tools.<br>
>><br>
>> So here's what I think I've come to:<br>
>><br>
>> 1. For now, we create two documents: an instructor's guide that doubles<br>
>> as a textbook (no harm in learners reading notes for instructors, and<br>
>> possibly some benefit), and a notebook that interleaves point-form notes<br>
>> with code examples that instructors will use for lecturing, and learners<br>
>> will be given as a starting point.<br>
>><br>
>> 2. We build a tool to extract point-form notes from an IPython Notebook<br>
>> to create the "objectives.html" and "keypoints.html" sections that are<br>
>> %include'd in #1 above.  This will help keep the notebook and the guide<br>
>> in step; whoever changes the notebook will still have to read the<br>
>> section of the guide to make sure, but it's a step.<br>
>><br>
>> 3. The code cells in our notebooks have markers for the instructors and<br>
>> the learners to fill in.  For example, instead of giving people:<br>
>><br>
>>       for char in "GATTACA":<br>
>>           if char == "A":<br>
>>               print "found an A"<br>
>><br>
>> we have:<br>
>><br>
>>       for ________ in "GATTACA":<br>
>>           if ________:<br>
>>               print "found an A"<br>
>><br>
>> Filling in the ________'s in the code snippets forces the instructor and<br>
>> the learners to do some typing. As a bonus, if chosen judiciously they<br>
>> will also encourage both to focus on the key features of the example.<br>
>><br>
>> But there are problems.  (You knew there would be...)<br>
>><br>
>> * (medium-sized) In order to extract stuff from notebooks for use<br>
>> elsewhere, we need a way to tag the cells that contain objectives, notes<br>
>> for the key point summary, etc., so that our tool can find and<br>
>> differentiate them.  I *think* this can be done via a plugin: the<br>
>> notebook has an extensible metadata field per cell, which we've already<br>
>> exploited for another tool, so adding something that allows "right click<br>
>> and select tag" should be straightforward. It would be nice if this info<br>
>> was available as a class on the HTML element containing the material, so<br>
>> that it could be styled via CSS, but that's a bonus.<br>
>><br>
>> * (large) Literal ________'s in our code will make it invalid, so our<br>
>> notebooks either won't have any output (because we didn't execute the<br>
>> code) or will be littered with error messages (because we did).  The<br>
>> former's not bad, but if we do that, we need two version of each<br>
>> notebook: one with the blanks, and one with them filled in.  As always,<br>
>> keeping variants of a single document in sync will be a pain.<br>
>><br>
>> If the code in cells was stored as HTML, we could put something like<br>
>> <span class="fillin">char == "A"</span> in the code, then use Javascript<br>
>> to display ________, erase it when the learner started typing, or fill<br>
>> it in with the right answer when the learner just wanted to catch up or<br>
>> see the answer. Problem is, the code *isn't* stored as HTML; it's stored<br>
>> as JSON that looks like this:<br>
>><br>
>>       {<br>
>>        "cell_type": "code",<br>
>>        "collapsed": false,<br>
>>        "input": [<br>
>>         "import math\n",<br>
>>         "print \"pi is\", math.pi\n",<br>
>>         "print \"square root of 5 is\", math.sqrt(5)"<br>
>>        ],<br>
>>        "language": "python",<br>
>>        "metadata": {},<br>
>>        "outputs": [<br>
>>         {<br>
>>          "output_type": "stream",<br>
>>          "stream": "stdout",<br>
>>          "text": [<br>
>>           "pi is 3.14159265359\n",<br>
>>           "square root of 5 is 2.2360679775\n"<br>
>>          ]<br>
>>         }<br>
>>        ],<br>
>>        "prompt_number": 1<br>
>>       }<br>
>><br>
>> We could use character offsets to identify subsections of the code, then<br>
>> intercept rendering to insert span elements, but that way lies madness...<br>
>><br>
>> So as I said at the outset, I feel like I'm thrashing here, and would<br>
>> welcome suggestions on how to proceed.<br>
>><br>
>> Thanks,<br>
>> Greg<br>
>><br>
>> _______________________________________________<br>
>> IPython-dev mailing list<br>
>> <a href="mailto:IPython-dev@scipy.org">IPython-dev@scipy.org</a><br>
>> <a href="http://mail.scipy.org/mailman/listinfo/ipython-dev" target="_blank">http://mail.scipy.org/mailman/listinfo/ipython-dev</a><br>
><br>
><br>
<br>
_______________________________________________<br>
IPython-dev mailing list<br>
<a href="mailto:IPython-dev@scipy.org">IPython-dev@scipy.org</a><br>
<a href="http://mail.scipy.org/mailman/listinfo/ipython-dev" target="_blank">http://mail.scipy.org/mailman/listinfo/ipython-dev</a><br>
</div></div></blockquote></div><br><br clear="all"><br>-- <br>Gabriel Becker<br>Graduate Student<br>Statistics Department<br>University of California, Davis<br>
</div>