<div dir="ltr"><div>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:<br>
</div><div><br></div><div>* assume user knows very little about technologies</div><div><br></div><div>* 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</div>
<div><br></div><div>* examples should not require a running kernel, and should be useful as shown (eg, not like [2])</div><div><br></div><div>* markdown documentation should be useable by any kernel (eg, should not make use of kernel-specific items)</div>
<div><br></div><div>* docs should try to be as notebook-specific as possible (we are writing docs specifically for this use)</div><div><br></div><div>* 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</div>
<div><br></div><div>Of course we will share all of these back to the community at large. Speaking of that, I notice that:</div><div><br></div><a href="https://github.com/ipython/ipython/blob/master/docs/source/about/license_and_copyright.rst">https://github.com/ipython/ipython/blob/master/docs/source/about/license_and_copyright.rst</a><div>
<br></div><div>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?</div>
<div><br></div><div>If anyone else has ideas or comments on constructing useful documentation for all uses, please let us know. Thanks!</div><div><br></div><div>-Doug</div><div><br><div><br></div><div>[1] - <a href="http://daringfireball.net/projects/markdown/syntax">http://daringfireball.net/projects/markdown/syntax</a></div>
<div>[2] -  <a href="http://nbviewer.ipython.org/github/ipython/ipython/blob/1.x/examples/notebooks/Part%204%20-%20Markdown%20Cells.ipynb">http://nbviewer.ipython.org/github/ipython/ipython/blob/1.x/examples/notebooks/Part%204%20-%20Markdown%20Cells.ipynb</a></div>
</div></div>