Re: [Couchdb Wiki] Trivial Update of "CouchDB_in_the_wild" by wentforgold

[MC Brown <mc...@couchbase.com>]

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: http://docs.couchbase.org/couchbase-api/index.html

> 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 (https://github.com/CouchOne/CouchDocs 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

--
MC Brown, VP of Documentation
mc@couchbase.com
Skype: mcmcslp Mobile: +44 7411 295711 (GMT)