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