On Tue, Jun 14, 2011 at 9:37 AM, Jan Lehnardt <j...@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 > -- > > > > 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. >> > >
If Noah agrees with the doc system then I'm in. I point him out specifically because of the work I know he was responsible for on the O'Reilly book and he had a couple iterations of how to maintain a large amount of text with code and image inserts so AFAICT he's probably in the best position to make a judgement of what'll be awesome or not. Except for the comments. I agree that we need to allow for super easy contributions without a login, but comments are a blight on the internet. Perhaps a mailto link that opens up dev@ or a form that just emails dev@ or maybe a special docs@ list. If we're gonna work on making our docs all pretty, the last thing we should do is give the collective internet-as-five-year-olds group a big marker to draw all over them.
