>> It's simple to have CouchDB render Markdown.
And even more simple to "render" HTML.
> I think the closer to doc stays to the code the more apt it is to be read,
> written, and useful.
And the closer to HTML we keep it, the more likely it is to be broadly useful
without people having to learn new syntaxes, or set up yet more layers of
technology in order to view and use it.
> I'm wondering how useful it might be to have some of these markdown files
> reside with the code in the repository.
I depends what we want to do here.
There are roughly four types of documentation I can think of:
* Official project documentation
* An official project wiki, edited by users and other interested parties
* Blogs, tutorials, and other community resources
* Larger third-party projects, like a book
My views on these are:
Official project documentation should be in the official repository, and
ideally, integrated in such a way that it can be hosted on
http://couchdb.apache.org/ as well as being bundled up in the tarball, and
installed on a users system under /usr/local/share/doc/couchdb for off-line
viewing. This documentation should as close to unprocessed HTML as possible.
Because it takes significant effort to get commit privileges for the official
repository, having a set of strict authorship guidelines for this documentation
should not be a problem.
An official project wiki should be hosted on ASF infrastructure. The software
we use is largely unimportant, as long as it works and is reliable. Because
this would be hosted and served by a web application that needs to restrict
content and include administration debris, it makes sense to use whatever
format makes the most sense for that. Given the popularity of Mediawiki, it
would seem like an obvious choice.
I don't want to sacrifice utility for some intangible sense of pride at being
able to "dog-food" the app. CouchDB is not a CMS; it's a database. If there is
an external effort that produces a production quality CMS or wiki, then by all
means, it would be cool to consider that further down the line.
Blogs, tutorials, and other community resources, including books, should feel
free to publish documentation using clay tablets or papyrus, if they so choose.
How to integrate, promote, and respond to that content should be discussed on a
case-by-case basis. There is no one-size-fits-all solution to be found here.
