couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marco Monteiro <ma...@textovirtual.com>
Subject Re: [VOTE] Apache CouchDB new docs proposal
Date Sun, 27 Nov 2011 12:10:41 GMT
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?

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