couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Randall Leeds <>
Subject Re: [VOTE] Apache CouchDB new docs proposal
Date Sat, 26 Nov 2011 23:14:18 GMT
On Sat, Nov 26, 2011 at 14:42, Dale Harvey <> wrote:
> I will happily volunteer to work on generating html output from whatever we
> store the documentation in, ultimately I think they should be integrated
> into futon, and I would request that whatever the documentation is stored
> in, that its its reasonably easy to parse and wrangle into your own output *

You bring up an amazing point. However we ship the documentation in
the source, it'd be cool to install it at /_docs or something. This
would be straightforward. It'd be easy for futon to embed that (but it
wouldn't be tied to futon). I'd love if the startup message had a link
to the "Getting Started" guide or something. That makes it a lot
friendlier for someone to browse the docs after installing CouchDB on
a remote server.


> Also volunteer to do any work on the website needing done
> Cheers
> Dale
>  * I am currently wrestling with the otp team changing the erlang
> documentation format every release and breaking erldocs
> On 26 November 2011 22:20, Randall Leeds <> wrote:
>> On Sat, Nov 26, 2011 at 11:41, Noah Slater <> 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
>> >
>> > 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:
>> >
>> >
>> >
>> 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

View raw message