couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Randall Leeds <randall.le...@gmail.com>
Subject Re: [VOTE] Apache CouchDB new docs proposal
Date Sat, 26 Nov 2011 22:20:22 GMT
On Sat, Nov 26, 2011 at 11:41, Noah Slater <nslater@tumbolia.org> wrote:
> That sounds reasonable. The sort of thing you'd get in an appendix, if this
> were a book. A blow by blow description of each CouchDB feature, config
> variable, URL parameter, etc.
>
> Seeding the wiki is a problem. The documentation should live in one place,
> and one place only. Seeding the wiki is a one time process, but both the
> docs we are discussing and the wiki are living documents. It is too hard to
> keep this kind of duplication up to date, and I will go out on a limb and
> say that, eventually, the disparities will cause the docs to do more harm
> than good.
>
> What I'd like to propose is that we make the docs we have in the source
> directly accessible on the web.

Absolutely. The main reason I want to see docs live in the source is
so that it's easy to tie a version of the docs to a release of the
source. That way, we can look at hosting a documentation site that has
docs for each version of CouchDB. See http://nodejs.org/docs/

>
> How do we do that?
>
> The current CouchDB site is held in Subversion, and there is ASF
> infrastructure that mirrors this to a public location. Could we get
> something similar set up to host the contents of a specific folder held in
> Git? I don't know, but it's worth investigating.
>
> The only other option would be to host out of Git, like this:
>
> http://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob_plain;hb=HEAD;f=README
>

FWIW I wouldn't mind adding a step to the release procedure to export
the docs @ some tag and push them up to the SVN site in a new folder.
It's not the most automatic and elegant thing in the world, but it's
simple and works today.

Randall

Mime
View raw message