[yt-dev] Request comments/vote on use of notebooks in yt docs

[Cameron Hummels]

Hey everyone,

The documentation sprint is next Monday and Tuesday for those of you who
want to participate.  I'll send out another email regarding that in the
next day or so.

In preparation for that, though, I wanted to request input from the
developer community on something related to the docs.

Right now, the cookbook page contains a lot of recipes for doing various
things, and I think it is hugely beneficial to the community to maintain
this (I personally use this page a lot too!).  However, with the advent of
ipython notebooks over the last year, we are faced with a question: should
we move toward incorporating more notebooks into our documentation, and
specifically, do you we want to transfer the existing cookbook to a series
of notebooks for each task?

Benefits:
--Portability: users can download an entire notebook for both viewing how
it should work as well as being able to execute it locally on their own
datasets
--Illustrative: Interim steps in a cookbook can produce output that can
show up inside the notebook, instead of being a single script which
generates an image/output at the end (as is the case in the current
paradigm)
--Narrative: notebooks provide more space for narrating each step, instead
of confining any narrative to comments in the recipe itself

Disadvantages:
--Work: it is going to take a decent amount of work to move all of the
recipes over from the existing cookbook to individual notebooks
--Bulking of repo: In the current paradigm, images associated with each
recipe are generated dynamically on the server by executing each script,
thereby minimizing the number of files that need to be tracked by
mercurial.  By moving to a notebook with images that are embedded in each
notebook, we'd potentially increase the footprint of the repository
substantially, especially if there were frequent updates of individual
recipes.

I also like the yt bootcamp notebooks that Matt put together a year ago.  I
think they are great for getting new users up to speed on how to use
various aspects of the code.  Perhaps this notebook could make its way into
the beginning of the cookbook for a more streamlined approach to the
documentation?

So now is your chance to vote:

Move cookbook to ipython notebooks? +/- 0-1?

Move yt bootcamp to cookbook? +/- 0-1?

Comments?  Suggestions?

Cameron

-- 
Cameron Hummels
Postdoctoral Researcher
Steward Observatory
University of Arizona
http://chummels.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.spacepope.org/pipermail/yt-dev-spacepope.org/attachments/20131022/7768dff5/attachment.htm>