couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Lehnardt <...@apache.org>
Subject Re: [VOTE] Apache CouchDB new docs proposal
Date Sun, 27 Nov 2011 19:19:36 GMT

On Nov 27, 2011, at 13:10 , Marco Monteiro wrote:

> I was under the impression that CouchBase might be available to give their
> (docbook) documentation to the project so that it can be used as the
> starting point. This would spare the community a lot of the work.
> 
> Jan, is this still possible, and can it be worked out so that the
> documentation
> is in couchdb repo before, lets say, the end of the year?

We are working through the details, I'll update this thread when I know
more. Thanks for your patience :)


Cheers
Jan
-- 
> 
> On 26 November 2011 23:40, 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