couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Robert Newson <rnew...@apache.org>
Subject Re: [VOTE] Apache CouchDB new docs proposal
Date Sun, 27 Nov 2011 11:54:44 GMT
Noah: That one is on Jan.

On 26 November 2011 23:45, Noah Slater <nslater@tumbolia.org> wrote:
> Also, Bob, you mention Couchbase stepped in to fill this gap.
>
> Do you know where we can see the fruits of that labour? If licensing
> permits, we might find it useful to take that as a starting point, or at
> least reference the sections there as we can reference parts of the
> existing wiki, while compiling this stuff.
>
> On Sat, Nov 26, 2011 at 11:40 PM, Noah Slater <nslater@tumbolia.org> wrote:
>
>> Cool idea.
>>
>> Just to re-iterate, we should keep things as simple as possible for now. I
>> think we can get away with maintaining a set of easy to read, easy to edit
>> HTML files that are served up along with Futon. These would be kept in the
>> source exactly the the current set of HTML files that make up Futon are. We
>> might want to create a /_docs URL handler, but we can get to that later.
>>
>> I have created a wiki page:
>>
>> http://wiki.apache.org/couchdb/SourceDocumentation
>>
>>
>> I suggest that we start collecting a proposed table of contents here, or
>> even the actual documentation. Once we have enough to work with, I plan on
>> moving it in to the source, and hooking up all the relevant parts of the
>> system. Then, when all that is done, we can re-visit how we're going to
>> publish this on the web, and whether or how we tie that to our release
>> procedure.
>>
>> First things first, let's get the documentation written down, and
>> collected together before we continue.
>>
>> I suspect a lot of it may already exist on the wiki in one form or
>> another, in which case, it should be good enough to just create a section
>> for it as it will appear in the final documentation, and then include a
>> reference to where it can be found on the wiki. Once we migrate the
>> documentation over to its final home, we can go about resolving these
>> references and cleaning things up.
>>
>>
>> On Sat, Nov 26, 2011 at 11:14 PM, Randall Leeds <randall.leeds@gmail.com>wrote:
>>
>>> On Sat, Nov 26, 2011 at 14:42, Dale Harvey <dale@arandomurl.com> 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.
>>>
>>> -Randall
>>>
>>> > 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 <randall.leeds@gmail.com>
>>> wrote:
>>> >
>>> >> 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