couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Noah Slater <nsla...@tumbolia.org>
Subject Re: [VOTE] Apache CouchDB new docs proposal
Date Mon, 28 Nov 2011 00:26:16 GMT
Cool.

For now then, I'd say we wait for an update from Couchbase before moving
forward.

If people want to jot down their ideas on the wiki page I created, I think
that would be productive.

http://wiki.apache.org/couchdb/SourceDocumentation

On Sun, Nov 27, 2011 at 7:19 PM, Jan Lehnardt <jan@apache.org> wrote:

>
> 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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message