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