[IPython-dev] GH wiki updates

[Brian Granger]

Hi,

I have been working on the GitHub wiki for the last few days and
wanted to summarize my progress:

* I have gone through and created pseudo namespaces for our wiki pages
using prefixes in the page names such as "Dev:" and "Install:" and
"Cookbook:".   Please use this from now on.
* I have audited our content and removed all pages that are outdated.
I haven't removed them from the wiki yet - they just have a "Trash:"
prefix.  Please look through these and see if you are OK with my
decisions.  If you want to keep  something in the Trash, please update
it as you move it back out of the Trash.
* I have moved all of our developer docs to a single location - the GH
wiki.  There is an open PR to remove this stuff from the Sphinx docs.
I have gone through and edited much of this material - it was a
horrible mess.
* Please help keep the wiki organized.
* Right now our wiki has content in 3 different formats.  From now on,
please use Markdown for all new pages - I have rewritten quite a bit
of content in Markdown.

Some general observations about our documentation from working on it
for a few days...

Our biggest problem is that our documentation is too *deep* and *narrow*.

* It is deep because the docs we do have are far too verbose.  This
means that none of us is willing or able to maintain it.  In many
cases, we aren't even aware of what documentation exists so bits and
pieces get rewritten all over the place.
* It is narrow because there are huge topics that don't have much documentation.
* So...*PLEASE* be extremely concise when you are writing documentation.
* Also, the length of the documentation should be proportional to the
stability of the code/API.  Rapidly evolving code should have minimal
documentation or we will never be able to keep it updated.  More
stable parts of the code base should have more complete docs.

We definitely need to have further discussions about how we want to
approach our documentation.

Cheers,

Brian



--
Brian E. Granger
Cal Poly State University, San Luis Obispo
bgranger at calpoly.edu and ellisonbg at gmail.com