couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benoit Chesneau <bchesn...@gmail.com>
Subject Re: [Couchdb Wiki] Trivial Update of "CouchDB_in_the_wild" by wentforgold
Date Tue, 14 Jun 2011 14:23:12 GMT
On Tue, Jun 14, 2011 at 6:37 AM, Jan Lehnardt <jan@apache.org> wrote:
> 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
> --
>
>
It would be a great solution indeed. If we can also manage to build
doc distributed with the code would be awesome.

Also I hink like davisp suggested, that as developer when we add a
feature in the code or see one non documented we should have to put it
in the documentation like the Django project does. We already have the
same kind of obligation with tests so doc shouldn't be a big problem
imo.

- benoƮt

Mime
View raw message