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 Sat, 26 Nov 2011 19:41:10 GMT
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.

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


The only problem being how links work. Relative links wont work properly,
because the filename is passed in as a query string parameter. Is there any
way around this that doesn't involve a proxy and a bit of mod_rewrite?

As for the use-case, this is an important question.

Is it important that this stuff be included in the source? There are two
reasons why this might be the case. Firstly, it allows people with only the
source (and no net connection) to read the documentation. It's not the
1980s anymore, so this doesn't really seem too important. Secondly, it lets
us enforce a policy of updating the docs as you update the features. This
one seems very important.

Is it important for this stuff to exist in multiple formats, or is HTML
just fine? If we used a document toolchain like DocBook or LaTeX, we get a
bunch of nice output options for PS, and PostScript, and Ghostscript, etc.
But seriously, who reads documentation like that anymore? Again, it's not
the 1980s anymore. I think that HTML is just fine. If you want a PDF, your
browser can do that.

And to this end (and if you're called Jan or J. Chris, you've already
pre-emptied me) I suggest we write our documentation in HTML. No toolchain,
no conversion, no transformation, no XML nonsense, no fuss. Just straight
up, simple, HTML.

We did this for the CouchDB book, and it works just fine:

https://github.com/oreilly/couchdb-guide/tree/gh-pages/draft

https://github.com/oreilly/couchdb-guide/blob/gh-pages/draft/why.html


If you find that hard to edit, then god help you, no amount
of intermediary format is going to help! ;)

On Sat, Nov 26, 2011 at 7:14 PM, Robert Newson <rnewson@apache.org> wrote:

> For me, the goal would be for docs/ to contain at least a brief
> description of every couchdb feature. I specifically don't expect to
> see introductory text, example views, tutorials, etc, except where
> needed to describe core features. One thing we've missed for a long
> time, and Couchbase had to step in and fill this gap for us, is a
> genuinely comprehensive list of everything couchdb can do (all those
> funny corners like ?batch=ok, all_or_nothing, etc).
>
> I hope this answers your secondary questions, but I'd add that I'd
> expect to see the docs/ folder used to seed the wiki and other
> documentation efforts. It would become part of our procedure to insist
> that a commit that adds a feature also adds documentation for that
> feature (the way it ought to include verifying tests).
>
> B.
>
> On 26 November 2011 18:23, Noah Slater <nslater@tumbolia.org> wrote:
> > Let's forget about the format or the toolchain for now, they're
> bikesheds.
> >
> > What is the goal of this effort?
> >
> > We want documentation in the source, sure. But why? What kind of
> > documentation is it going to be? What topics will it cover? Can anyone
> come
> > up with a suggested outline for it? i.e. Table of Contents
> >
> > Secondly, who's going to be use it, and in what situation? Typical
> > use scenarios please!
> >
> > Thirdly, who's going to write it?
> >
> > Once we have that nailed down, we can move forward sensibly.
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message