On 17 June 2011 09:19, Christian Schneider <[email protected]> wrote: > I know that I have proposed this before and then got the answer that this > was discussed already. Still I have the feeling that everybody dislikes the > current way we build our website.... so again a try :-)...
I'm not sure you realise how much dislike there is for wikis? > I would even go a step farther and do as much of the website on the wiki as > possible. Dan Kulp has written an exporter script that syncs the wiki to > static pages so the admins can live with it. I've now worked on many OSS projects over the years and I can honestly say wikis are a huge PITA for managing open source documentation & websites. Its a great example of theory not matching practice. IMHO the wiki should be for user submitted content which then gets merged into source control and versioned & branched. You rarely ever get much user submitted content anyway; most of the hard work is done by the committers; who generally prefer to use things like, source control, branching, merging, a text editor or an IDE! To be able to do things like, grep, search & replace. Or wacky things like hack documentation when on a plane. Commit documentation *with* code changes so they are always in sync; so you can be documenting experimental features in trunk or merging docs from production releases to trunk etc. So use a wiki for arbitrary user submitted content (you're still open to any contribution from non committers); then let committers use the best tools they have - source control & powerful editors to merge contributions into versioned releases & versioned documentation sites; so user get the documentation which actually matches their exact version & pages are not littered with "if you are on version X then... else if version Y then...." like the Camel pages are for example. Wikis don't help committers and don't help users (as you end up with crap everywhere from different versions - or worse documentation for stuff thats not even released yet); all just in case we hope one day someone will turn up and dump a load of useful stuff in the wiki (that never really happens). Incidentally I'm even finding the argument that a wiki is the easiest way to get contributions to have less and less value these days since github. Its actually easier for a total newbie to come along, fork an apache project's git repo on github.com, edit some text files & do a pull request than it is to pester folks for write access to the wiki first before they can even begin to contribute anything. The wiki has a much larger barrier to entry than github. Imagine for a second, you are a newbie - you've seen some issue or have an idea for a little page; with github 2 clicks, 20 seconds later you're editing the file in question or writing the new file then firing off the pull request and getting on with your life doing something else. With a wiki you try editing; doesn't work, so you shoot off an email for access then wait. Then after a random time period of hours to days you get more mails then at some point later, you get the ability to login again to the wiki and hopefully you can now edit the page. By the time you get access you've probably forgotten what you were gonna do in the first place :) So I'm tempted to suggest, to simplify things - just scrap the wiki entirely. If you had the choice of submitting content to a source control system or a wiki; I suspect plenty of contributors would go for the github route as its easier & lets folks get started contributing immediately with the best tools available without waiting for some humans to read emails and do stuff; there's no pestering people to get access just to be able to write some text files in a web browser (which isn't ideal anyway). Though that might be a little to radical for some who still like the concept of a wiki despite its huge practical flaws, so how about we say, use source control for the main documentation & site then have a wiki as the 'wishing well' so we can hope that one day some non-committers come along and chuck useful stuff in there. If they do, great, we can merge it into source control for the relevant release they're talking about. If not, its just another thing for infra to maintain. -- James ------- FuseSource Email: [email protected] Web: http://fusesource.com Twitter: jstrachan, fusenews Blog: http://macstrac.blogspot.com/ Open Source Integration and Messaging
