[IPython-dev] Notebooks for humanities students

[Doug Blank]

We've just begun a month-long, intensive project on using Notebooks for
humanities students (weird, huh? I'll explain later). One of the first
things we're tackling is creating appropriate documentation for this use.
Here is what we are thinking, especially for Markdown:

* assume user knows very little about technologies

* examples should not refer to HTML tags to explain the output (eg, the
Daring Fireball examples [1] describe effects in terms of HTML tags rather
than rendered forms); show the raw version *and* rendered form

* examples should not require a running kernel, and should be useful as
shown (eg, not like [2])

* markdown documentation should be useable by any kernel (eg, should not
make use of kernel-specific items)

* docs should try to be as notebook-specific as possible (we are writing
docs specifically for this use)

* we are trying to be complete... documenting everything that Markdown in
the notebook can (and cannot do); we are studying the "marked" project's
test suite

Of course we will share all of these back to the community at large.
Speaking of that, I notice that:

https://github.com/ipython/ipython/blob/master/docs/source/about/license_and_copyright.rst

doesn't have a license for documentation/notebooks. Would it be possible to
add a Creative Commons license to that for documentation? I'd be glad to
add a pull request if a particular document license is indicated. And then
we'll use the same license. Which?

If anyone else has ideas or comments on constructing useful documentation
for all uses, please let us know. Thanks!

-Doug


[1] - http://daringfireball.net/projects/markdown/syntax
[2] -
http://nbviewer.ipython.org/github/ipython/ipython/blob/1.x/examples/notebooks/Part%204%20-%20Markdown%20Cells.ipynb
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20140702/c1259d30/attachment.html>