couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sebastian Cohnen <sebastiancoh...@googlemail.com>
Subject Re: CouchDB Wiki / Documentation
Date Sat, 06 Mar 2010 15:54:29 GMT

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.

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



Mime
View raw message