couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Noah Slater <nsla...@tumbolia.org>
Subject Re: CouchDB Wiki / Documentation
Date Sun, 07 Mar 2010 15:07:51 GMT

>> 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.


Mime
View raw message