incubator-couchdb-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sebastian Cohnen <sebastiancoh...@googlemail.com>
Subject CouchDB Wiki / Documentation
Date Fri, 05 Mar 2010 19:36:53 GMT
Hi folks,

lately I tried to improve various areas in the CouchDB Wiki. My list is getting bigger and
bigger and everyone will agree with me, that there is still a lot of work to do. So, I'm sorry
devs, you will be asked a lot of questions in the next days and weeks ;)

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. As a first step we want to suggest using
Markdown 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). 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? ;)

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

Pros for a git(hub) based interim solution:
+ distributed, easy to work offline
+ contribution is very easy (fork, edit, push/pull request)
+ easy to comment on stuff you don't understand
+ easy to integrate files (like images, demo-code, ...)
+ easy to have smth. like a official repo with reviews/QA

For me personally I think having like a official repository and a open wiki in parallel would
be nice approach. The last few weeks I dug into the current structure of the wiki... it needs
lots of improvement and restructuring, imho (lots of outdated stuff, duplication, nonsense,
...). I think documentation needs a bit more structure so it's a lot easier for everybody
to find one's way through all that information.

What do you think? You can ping me on IRC (tisba) anytime, but the ml should be the place,
where the discussion takes place (so that everyone can participate).


Sebastian // tisba
Mime
View raw message