couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From till <klimp...@gmail.com>
Subject Re: CouchDB Wiki / Documentation
Date Sat, 06 Mar 2010 18:05:30 GMT
On Sat, Mar 6, 2010 at 4:54 PM, Sebastian Cohnen
<sebastiancohnen@googlemail.com> wrote:
>
> On 05.03.2010, at 21:08, Noah Slater wrote:
>
>> This should be on dev@ I think, so moving there.
>>
>> Please remove user@ from the address in your replies to this message.
>>
>> On 5 Mar 2010, at 19:36, Sebastian Cohnen wrote:
>>
>>> but back to topic: MoinMoin sucks! It's unbelievably slow, throws 500s all the
time and don't forget the syntax - pure hell when you seriously want to work with it. I've
talked with Jan and he has been recently thinking of a replacement.
>>
>> From an old blog post:
>>
>> We were discussing Apache infrastructure, and I was joking about how much I hated
JIRA. Robert Newson suggested that having to pick between JIRA and Bugzilla was Hobson's choice,
 but I countered with Sophie's choice, and his riposte was Morton's fork. When we were cautioned
to avoid Buridan's ass, I commented "that's what she said!"
>>
>>> As a first step we want to suggest using Markdown
>>
>> Just use HTML, it is way simpler.
>>
>>> and git from now on - at least for documentation purposes
>>
>>> Once we (or better I) have enough translated from MoinMoin to Markdown we could
start linking from the wiki to Github (as it renders markdown nicely for you).
>>
>> Nice idea, but absolutely not.
>>
>> Official project documentation should be on couchdb.apache.org and the wiki must
be on apache infrastructure. Unofficial stuff, like our O'Reilly book, is fine elsewhere,
but that's all it can be - as far as I understand the situation.
>>
>>> We think that this approach is likely to work best as an interim solution before
we have a ass-kickin' couch-wiki solution. Once that's done, we can easily import the markdown
stuff. or maybe markdown+git works so well, so that it stays the preferred way - who knows?
;)
>>
>> Avoid Markdown! It solves nothing and introduces problems.
>
> hmm, I personally like markdown. It's simple to read/write and easy to parse. Writing
HTML is much more painful and without strict conventions you get very messy code.

+1

>>> This is only a suggestion and we really want your opinion. I think the rudimental
requirements are quite clear:
>>> * a faster and more reliable system
>>> * very easy to contribute
>>> * easy and easy to learn syntax
>>> * being able to work offline (at least for me that would be awesome)
>>> * easy way to do some QA
>>
>> Whatever we choose must run on ASF infrastructure if it is to be considered official.
>
> I think you misunderstood me on this point. I didn't want to suggest making Github the
new place for "official" documentation. I see git(hub) more like a working platform. Static
HTML export could be placed on couchdb.apache.org/docs or where ever you like.

+1

I think this sounds pretty good and as someone earlier said, if you
want to create a toolchain and get people to contribute. That's
awesome. I'd help out with content as well, if someone checks my
gibberish Engrish.

Generaly, I think another wiki would be nice. I'm missing structure
right now and clarity. I don't know if we can get this going with
moin-moin. But I don't know which other wiki would be better, as (no
offense to the wiki overlords) all seem to suck in one way or another.

Sometimes I'm thinking even docbook would be nice. :)

All in all, I'd like CouchDB move into the direction of docs.php.net.
The most awesome part are the comments and a nifty little switch (for
admins/official contributors/developers) to transform a comment into a
docbug to either fix an example/paragraph or extend it with valuable
info provided through the comment system.

Till

Mime
View raw message