We should create better MarkDown documentation and then split it into sections that http://rtomayko.github.com/ronn/ can easily consume to create man pages.
We can then use these MD files to help auto-generate the ReadME.md file
I don't think this issue is entirely relevant anymore. I'm going to close it.
I do, however, think that discussing an overall documentation strategy is worthwhile.
Do you mean that there should be new markdown files containing the Ronn documentation, in addition to the in-code markdown comments, or should this come straight from the in-code markdown comments?
In the case that new markdown files should be created, I think that there could be a docs/ directory that contains a set of markdown documentation files. These could be compiled into Ronn-compatible markdown (and then converted into man pages automatically) and readme markdown when needed, and placed in their respective places. (post-commit hook?) That's the idea, right? The less that we have to repeat ourselves, the less likely that we'll forget to repeat ourselves when we need to, after all.
(well, i couldn't call the folder docs, that's already taken by the doccu stuff...)
This isn't relevant to our documentation process any longer. Between the handbook and jitsu's readme I believe changing the process to use ronn is late in the game now.