couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From MC Brown>
Subject Re: [Couchdb Wiki] Trivial Update of "CouchDB_in_the_wild" by wentforgold
Date Tue, 05 Jul 2011 15:00:31 GMT
Hi everybody, 

Sorry for the delay in replying to this, a combination of illness and work. 

> Here is what is a rough outline of what I propose that solves many of the current problems.
This is a proposal and I am happy to amend, discard or accept it based on your comments.
> My company hired a top documentation writer (MC Brown of MySQL fame, who is unavailable
this week, but he'll pick up this thread eventually :) last year and he's been working on
our documentation ever since. Of course, since we are distributing a version of Apache CouchDB,
the bulk of the documentation overlaps with what is applicable to Apache CouchDB.

Right, and for those who have not already seen it we publish that here:

> In addition to producing the raw documentation, he also developed a documentations system
derived and improved from his experiences with the MySQL documentation system. It is based
on DocBook and you can find it on GitHub ( produced HTML
is in the gh-pages branch (ignore the last-modified date for a second)).

This is a slightly older version of the main code, but it's close enough to the current functionality
to be useful. 

> We'd be happy to both donate the documentation system and contents to Apache CouchDB
as well as have MC spend some of his time working on the official documentation (as well as
improving the build system) as any improvements would be mutually beneficial.
> The documentation system can be managed in version control and understands the notion
of releases (I'll leave it to MC to explain the details, if that is needed).

Quick version: the backend of the API reference is a metadocs systems that collects the core
API details (arguments, HTTP response codes, etc) and then outputs them in a standardised
format, both as a summary of the main API calls and the more detailed individual call information,
as seen in the current docs. In addition, each item is individually tracked against a version
number (including introduced, deprecated and removed versions). This means that you can generate
a version of the manual it will output only the information specific to the specified version.

In addition, individual sections of the docs can be switched on/off based on the version information.

There's more to it than that, but it solves one of the bigger problems of evolving products
and versions.  

> The documentation system itself does not yet solve the problem of a low barrier of entry,
but there are a few ways to achieve that. My favourite example of this is the PHP documentation
where there main docs are in DocBook (surprise) and each rendered HTML page has a comments
section open to anyone (including spam, alas, but that seems to be not a big issue). The PHP
documentation team has the capabilities to take a comment and make it a bug report with a
single click. Once the ticket is closed, the comment disappears, or is marked as "integrated".
I find that rather neat. Alternatively, we can start manually by embedding a Discuss on every
page that we maintain manually until we have a more integrated solution, small steps and all.
I don't think requiring users to sign up for JIRA to report a docs issue is a good idea.

Right, and just to add the perspective of the MySQL process, the comments at the end of all
online documentation pages could contain corrections and updates, and we would update the
docs with that information as the comments came in (much like the PHP solution). This makes
it easy to collect multiple comments and feeds from different people, while ensuring the docs
can be updated.


MC Brown, VP of Documentation
Skype: mcmcslp Mobile: +44 7411 295711 (GMT)

View raw message