[OH-Dev] Development documentation: Should we move it out of the wiki?

[Asheesh Laroia]

I have some general thoughts about developer documentation for the 
OpenHatch codebase. This email first describes how things are right now; 
then it links to other people doing things in what seem like nice ways; 
then it makes suggestions for what we could do.

But first, some...

Quick overview questions
------------------------

Dear reader, would you be any more (or less) willing to write dev 
documentation if we moved it from the wiki to the main git repo?

Dear reader, do you find our dev documentation hard to navigate, and would 
more structure help with that?

Dear reader, do you have experience from other code collaboration projects 
that can help guide us toward a good strategy for storing developer 
documentation?

How we do things now
--------------------

We store pages in our wiki here: 
https://openhatch.org/wiki/Category:Hacking_OpenHatch

We use this category for all developer documentation-type things so that 
it's pretty easy to find development documentation. The idea of putting 
these on the web is so that prospective contributors can click around in 
the comfort of a web browser. Also, in theory, this makes it easier to 
other people to write write dev documentation.

One thing I don't like about the wiki is that there isn't an obvious sense 
of "previous" and "next", or of hierarchy.

We store some things in the repo, like README.mkd (and now 
INSTALLATION.mkd and more). The nitty-gritty documentation, it seeems, I 
prefer to leave in the git repo. Storing this in git has the following 
advantages:

* The version of these documents that you read is in sync with the version 
of the code you have.

* I get to use my regular text editor to write the docs, not a web 
browser's editor in a <textarea>. (I could work around this by using a 
Firefox extension to use a regular editor.)

Other people's nice ways of doing things
----------------------------------------

Kitsune, a (open source) Django app, uses readthedocs.org + sphinx and 
stores their docs in their git repo: 
http://kitsune.readthedocs.org/en/latest/vendor.html

MediaGoblin seems to use a wiki for developer-oriented documentation: 
http://wiki.mediagoblin.org/Storage

Suggestion
----------

Maybe we should take all these development-oriented docs and move them out 
of the wiki and into the repository. A proposal:

* Make a directory called devdocs/
* Move the current wiki-based dev docs into there
* Use the Sphinx text format to do this
* Use readthedocs.org to host a copy of the dev docs rendered into HTML
* Create some hierarchy and prev/next structure for the new, Sphinx-ified 
docs

Then, we'd adjust the "source code etc." link on the OpenHatch site so 
that it goes to openhatch.readthedocs.org, to the page that talks about 
how to clone the repo and set up an instance.

What do you think?

-- Asheesh.

P.S. Also, I do admit that we do need more developer documentation.