ipython/ipython — pull request #3705 by dpsanders (2013-07-20 05:01:50+00:00)
Title: Completely rewritten IPython Notebook documentation: docs/source/interactive/htmlnotebook.txt

This is a complete rewrite of the main entry point to the documentation of the IPython Notebook.

It takes as a base the previous version and turns it into a comprehensive narrative description of the parts and operation of the IPython Notebook 1.0. The necessity of a narrative description was pointed out by @Carreau.

@Carreau also pointed out, in a blog post, that there is a great deal of nomenclatural confusion, since the word "notebook" is used to refer variously to (using the more specific terms that I have introduced in the documentation in this Pull Request):

- the IPython Notebook web application
- the "notebook space", which is the virtual computational space depicted in the web browser
- the notebook document, which is a *one-to-one* copy of the notebook space (i.e. they are "isomorphic")
- the JSON .ipynb notebook format
- the combination of all of the above, also known as... "the IPython Notebook" !

I have tried *very* hard to keep all this straight in the documentation. In particular, I *always* refer to the (IPython) Notebook app with capital 'N', and notebook document files or notebooks with small 'n'. I suggest that this is a simple typographic convenience which goes a long way to disambiguating things. It also has the subtle property of treating the Notebook as a proper noun, i.e. as a living thing ;)

I have tried to keep the informal "you can do this" style from the original document, but sometimes I reverted back to the "this can be done" style -- something to watch out for when reading over it, so we can uniformize the more informal style.

The style of the documentation is to introduce new terms by putting their names in italics, *like this*, with an informal description first, followed by a more detailed discussion.

Currently the documentation is a monolithic enormous file with too little structure, designed as a drop-in replacement for the previous file in order to have the text written and worry about formatting later.

In reality, this page obviously needs to be split up into several sub-pages, together with figures illustrating what is being discussed, cross-references, web links to the tools mentioned, etc, but perhaps it makes sense to do this after the monolithic version is merged for better atomicity.

A basic division should be made between a basic discussion for users, probably avoiding much mention of servers and kernels in particular, and a more advanced discussion containing all the details of those parts. I am unable to write that part due to my lack of knowledge, but am happy to review it for style, grammar, etc. But we definitely do need a detailed explanation of the kernel--server model, ZeroMQ, tornado, etc., as part of the documentation for IPython Notebook 1.0

Please let me have your frank comments on this PR.