couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Noah Slater <nsla...@apache.org>
Subject Re: [Couchdb Wiki] Trivial Update of "CouchDB_in_the_wild" by wentforgold
Date Tue, 14 Jun 2011 16:13:35 GMT

On 14 Jun 2011, at 15:54, Paul Davis wrote:

> If Noah agrees with the doc system then I'm in. I point him out
> specifically because of the work I know he was responsible for on the
> O'Reilly book and he had a couple iterations of how to maintain a
> large amount of text with code and image inserts so AFAICT he's
> probably in the best position to make a judgement of what'll be
> awesome or not.

Thanks, Paul. :)

If we're going to ship documentation with CouchDB, I have a good idea about how this should
look. I've actually done this before on a previous Autotools based project I was developing
for the GNU project itself.

We would create the following directory structure:

/doc
/doc/docbook
/doc/docbook/root.xml
/doc/docbook/ch1.xml
/doc/docbook/ch2.xml
/doc/docbook/ch3.xml
/doc/Makefile.am

You get the idea. The Makefile.am would contain a bunch of rules that would allow us to convert
this DocBook into plain text, DocBook, man, info, LaTeX, PostScript, and PDF as needed. All
very straight forward.

The generated files would be included as part of the distribution artefact, but would not
be included in the repository. This might also be a good opportunity to make that change for
our man page. You realise we have a man page, right? It's just that most people don't have
the tool needed to generate it, and we don't ship it by default. Which is a bug.

This documentation would then be installed locally on each system that CouchDB is installed
on (so that Futon can link right through to it) and we should also export it into the /site
directory so that it is available via the web for people who are browsing the CouchDB site.

Note, I am not sure where we want to draw the line between documentation and tutorial. An
API reference with basic examples would make sense for us to ship. CouchDB TDG, on the other
hand, is more tutorial based. I am not sure what kind of documentation CouchBase are working
on, but I doubt we'd want to move it all to the source tree.

> Except for the comments. I agree that we need to allow for super easy
> contributions without a login, but comments are a blight on the
> internet. Perhaps a mailto link that opens up dev@ or a form that just
> emails dev@ or maybe a special docs@ list. If we're gonna work on
> making our docs all pretty, the last thing we should do is give the
> collective internet-as-five-year-olds group a big marker to draw all
> over them.

A lesson we learnt from the CouchDB book: collecting comments via email sounds sensible, but
proves to be burdensome. Inline or in-page comments, or a bug tracker are both much better
solutions.
Mime
View raw message