From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Original-To: caml-list@sympa.inria.fr Delivered-To: caml-list@sympa.inria.fr Received: from mail1-relais-roc.national.inria.fr (mail1-relais-roc.national.inria.fr [192.134.164.82]) by sympa.inria.fr (Postfix) with ESMTPS id E919C7F2AA for ; Fri, 21 Dec 2012 18:52:32 +0100 (CET) Received-SPF: None (mail1-smtp-roc.national.inria.fr: no sender authenticity information available from domain of siraaj@khandkar.net) identity=pra; client-ip=128.177.27.134; receiver=mail1-smtp-roc.national.inria.fr; envelope-from="siraaj@khandkar.net"; x-sender="siraaj@khandkar.net"; x-conformance=sidf_compatible Received-SPF: None (mail1-smtp-roc.national.inria.fr: no sender authenticity information available from domain of siraaj@khandkar.net) identity=mailfrom; client-ip=128.177.27.134; receiver=mail1-smtp-roc.national.inria.fr; envelope-from="siraaj@khandkar.net"; x-sender="siraaj@khandkar.net"; x-conformance=sidf_compatible Received-SPF: None (mail1-smtp-roc.national.inria.fr: no sender authenticity information available from domain of postmaster@newcavia.khandkar.net) identity=helo; client-ip=128.177.27.134; receiver=mail1-smtp-roc.national.inria.fr; envelope-from="siraaj@khandkar.net"; x-sender="postmaster@newcavia.khandkar.net"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AlgHAFig1FCAsRuG/2dsb2JhbABFg0i6NBZzgh4BAQV5EAsYLiE2BhMUh20DD6xpDYlVi21qg2JhA4hii1OCcoRPhUyFEYMS X-IronPort-AV: E=Sophos;i="4.84,331,1355094000"; d="scan'208";a="187283975" Received: from newcavia.khandkar.net ([128.177.27.134]) by mail1-smtp-roc.national.inria.fr with ESMTP; 21 Dec 2012 18:52:31 +0100 Received: from [10.0.1.1] (pool-108-46-62-235.nycmny.fios.verizon.net [108.46.62.235]) by newcavia.khandkar.net (Postfix) with ESMTPA id 1107055FF8; Fri, 21 Dec 2012 12:52:31 -0500 (EST) Content-Type: text/plain; charset=iso-8859-1 Mime-Version: 1.0 (Mac OS X Mail 6.2 \(1499\)) From: Siraaj Khandkar In-Reply-To: Date: Fri, 21 Dec 2012 12:52:30 -0500 Cc: Ashish Agarwal , Wojciech Meyer , Anil Madhavapeddy , Benedikt Meurer , caml-list@inria.fr Content-Transfer-Encoding: quoted-printable Message-Id: <28D89228-06D5-4BBF-920F-6233737B8659@khandkar.net> References: <6A2113E2-2202-46EA-B0B0-7C80AA25B480@recoil.org> <88F05F0A-10A2-47AF-8285-575E95797E54@recoil.org> To: Siraaj Khandkar X-Mailer: Apple Mail (2.1499) Subject: Re: [Caml-list] OCaml wiki Or, it seems one can haz cake and eat it too! :) https://github.com/jgm/gitit On Dec 21, 2012, at 10:33 AM, Siraaj Khandkar wrote: > +1 >=20 > Wiki is a fun concept, but is a complete mess in practice. >=20 > It has some versioning capabilities, but not nearly as sophisticated as a= DVCS > such as Git. Obviously, there're editing capabilities, but not nearly as > productive as your favorite text editor. >=20 > Why force suboptimal tools on people that are interested in an optimal > programming language? ;) >=20 > Now, what about the maintainers? How do they even begin to keep track of = tiny > edits to 1000's of wiki pages? Queueing theory to the rescue! A pull requ= est > queue gives them a chance to audit the contributions in a sane manner (wi= thout > wasting their volunteered time). >=20 >=20 > On Dec 20, 2012, at 9:49 PM, Ashish Agarwal wrote: >=20 >> A wiki could be good but I strongly encourage any such effort to integra= te >> with ocaml.org, and to carefully weigh the pros and cons. Wikis make >> contributions easier, but you need someone to keep the content organized >> and do some basic quality control. Also, the structure of the documentat= ion >> is not very customizable. The question is whether pushing to a git repo >> (the current contribution method for ocaml.org) is so much harder (given >> that we're all programmers after all). >>=20 >> The tutorials page is a good candidate for converting to wiki format, but >> remember that a wiki is where all this content came from, and it eventua= lly >> got out of date. We could create wiki.ocaml.org, but then the question is >> how to make it integrate nicely with the rest of the pages that don't fit >> the wiki model. >>=20 >> Finally, which wiki software to use? None are very good, and who amongst= us >> is keen to hack into php code. My initial goal for ocaml.org was to use >> ocsigen and ocsimore, but there is a big upfront cost in getting such a >> site implemented. >>=20 >> Whatever the community decides, we can support and integrate with ocaml.= org. >> My only strong opinion is please don't build a separate unrelated site, >> with duplication of effort and and fragmentation of content. >>=20 >>=20 >> On Thu, Dec 20, 2012 at 6:50 PM, Wojciech Meyer wrote: >>=20 >>> Anil Madhavapeddy writes: >>>=20 >>>> On 20 Dec 2012, at 23:31, Benedikt Meurer < >>> benedikt.meurer@googlemail.com> wrote: >>>>>=20 >>>>> On Dec 21, 2012, at 0:22 , Anil Madhavapeddy wrote: >>>>>=20 >>>>>> Personally, I've got mixed feelings about wikis from experience with >>>>>> previous projects, since they get out of date very rapidly indeed. T= hey >>>>>> do work well if someone's maintaining it, but if that's the case, why >>>>>> not just push these tips and guides to the existing ocaml.org site? >>>>>>=20 >>>>>> I'm happy to run a wiki on the OCL infrastructure, but would strongly >>>>>> prefer contributions to the ocaml.org Git repo with all this good >>> stuff >>>>>> instead! If it really turns out we need a swanky wiki, that can be >>> arranged >>>>>> later... >>>>>=20 >>>>> Why not use the wiki provided by Github for the ocaml.org project? >>>>=20 >>>> That works too; Thomas has written a Github Markdown to HTML converter= in >>>> COW [1], and is using that to generate the OPAM website from the Github >>>> wiki (for the documentation that you see on opam.ocamlpro.com). >>>=20 >>> Yes, we could use github pages as long as they are searchable, I see no >>> problem with it. I think the biggest advantage of wiki would be that >>> everything would be in single place and hyperlinked. >>>=20 >>> As for protecting the wiki from being up-date emacswiki [1] is always a >>> great example that it is possible as long as people maintain their >>> webpages. Also, I feel that ocaml.org pages on github would be a good >>> entry point. >>>=20 >>> [1] http://emacswiki.org/ >>>=20 >>> -Wojciech --=20 Siraaj Khandkar .o. ..o ooo