couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Lehnardt <...@apache.org>
Subject Re: [Couchdb Wiki] Trivial Update of "CouchDB_in_the_wild" by wentforgold
Date Tue, 14 Jun 2011 13:37:24 GMT
Hooray what a great thread :)

I was on the cusp of starting one like it myself, although for different reasons. Turns out
the the details are all the same.

First, the wiki. While it works most of the time and includes most important information it
is neither a pleasure to look at nor to work with. It is great that it is a low barrier of
entry for contributions, which is a property that we should keep for any potentially other
documentation system.

In addition, the wiki has many other issues that are system inherent, like the inability to
link a code version with a docs version e.g.

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.

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)).

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).

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.

To get all of the above accomplished, I think it is worth thinking about an Apache CouchDB
Documentation team that can tackle the documentation related issues independently from the
core developers. Of course, interaction is required, especially when developers "forget" (hehe)
to document new features, but I think this is a good time to open up the project to more contributors
for different areas.

Note that I am not trying to push something my company has done, I'm just proposing a potential
solution to the problem of sub-par docs for Apache CouchDB with the strong desire to get this
fixed. I hope you like the proposal, but I'm eager to hear your comments.

What do you think?

Cheers
Jan
-- 



On 13 Jun 2011, at 11:23, Noah Slater wrote:

> I wish we could do something about the spam.
> 
> I don't like playing whackamole.
> 


Mime
View raw message