couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Lehnardt <...@apache.org>
Subject Re: CouchDB Wiki / Documentation
Date Sat, 06 Mar 2010 02:41:30 GMT
Hi,

I agree that the current wiki is a blocker for better documentation
but I'm not saying we should write software to replace 
wiki.apache.org/couchdb.

I like the idea of writing Markdown in Github. HTML would work
for me, but Markdown is a little easier to write (for me) and using
the Github infrastructure to manage forks, pulls and all that.

After producing some nice HTML we can put it up on

    http://couchdb.apache.org/docs or
    http://wiki.couchdb.org/ if there's an ASF licensing issue
    with non-committer content going on *.apache.org.

I imagine the HTML having "edit this" links back to the 
Github sources.

We can move content over gradually and link from the wiki
pages to the new place.

So we can get a well maintained and structured documentation
without losing the wiki for anyone who wants to use that.

I'd like a CouchDB-based wiki, but I don't want to go all NIH
on this, so we can work on that in parallel.

One thing I'd like that would be simple is have a small CouchApp
to run on say wiki.couchdb.org for online browsing. We can then
add a link to Futon that says "Download Documentation" to replicate
down the contents to the local CouchDB instance for offline use.

Cheers
Jan
--







On 5 Mar 2010, at 12: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.
> 
>> 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.
> 
> 


Mime
View raw message