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 mail3-relais-sop.national.inria.fr (mail3-relais-sop.national.inria.fr [192.134.164.104]) by sympa.inria.fr (Postfix) with ESMTPS id E58497F89E for ; Thu, 3 Apr 2014 17:52:41 +0200 (CEST) Received-SPF: None (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of amc79@cam.ac.uk) identity=pra; client-ip=131.111.8.151; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="amc79@cam.ac.uk"; x-sender="amc79@cam.ac.uk"; x-conformance=sidf_compatible Received-SPF: None (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of amc79@cam.ac.uk) identity=mailfrom; client-ip=131.111.8.151; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="amc79@cam.ac.uk"; x-sender="amc79@cam.ac.uk"; x-conformance=sidf_compatible Received-SPF: None (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of postmaster@ppsw-51.csi.cam.ac.uk) identity=helo; client-ip=131.111.8.151; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="amc79@cam.ac.uk"; x-sender="postmaster@ppsw-51.csi.cam.ac.uk"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AhsEAL+CPVODbwiXgWdsb2JhbABYg0HETYEfFg4BARYmKIIlAQEBAwEYVgsFCwsYFRkhNgYTFAeHSgMJCA3HVQ1Xhl8XiUaDEYE4EQEdMwcKgxqBFASWboMhizsDiH08gTU X-IPAS-Result: AhsEAL+CPVODbwiXgWdsb2JhbABYg0HETYEfFg4BARYmKIIlAQEBAwEYVgsFCwsYFRkhNgYTFAeHSgMJCA3HVQ1Xhl8XiUaDEYE4EQEdMwcKgxqBFASWboMhizsDiH08gTU X-IronPort-AV: E=Sophos;i="4.97,787,1389740400"; d="scan'208";a="55439366" Received: from ppsw-51.csi.cam.ac.uk ([131.111.8.151]) by mail3-smtp-sop.national.inria.fr with ESMTP/TLS/DHE-RSA-AES256-SHA; 03 Apr 2014 17:52:40 +0200 X-Cam-AntiVirus: no malware found X-Cam-ScannerInfo: http://www.cam.ac.uk/cs/email/scanner/ Received: from dhcp-172-17-168-132.eduroam.lapwing.private.cam.ac.uk ([172.17.168.132]:58345) by ppsw-51.csi.cam.ac.uk (smtp.hermes.cam.ac.uk [131.111.8.159]:587) with esmtpsa (PLAIN:amc79) (TLSv1:AES128-SHA:128) id 1WVjwV-0006oE-Z9 (Exim 4.82_3-c0e5623) (return-path ); Thu, 03 Apr 2014 16:52:40 +0100 Content-Type: text/plain; charset=iso-8859-1 Mime-Version: 1.0 (Mac OS X Mail 6.6 \(1510\)) From: Amir Chaudhry In-Reply-To: Date: Thu, 3 Apr 2014 16:52:39 +0100 Cc: Ocaml Mailing List Content-Transfer-Encoding: quoted-printable Message-Id: References: To: Yotam Barnoy X-Mailer: Apple Mail (2.1510) Subject: Re: [Caml-list] Activating wiki on ocaml github Thanks for taking the time to explain your thoughts. I've tried to read carefully and I summarise your main points to be: (1) some form of centralization of information is good/desired and (2) it should be possible for anyone to contribute to it I agree that the above two things are important but imho you haven't specif= ically explained why a *wiki* is the right solution. The one point that st= ands out is that it may feel more socially acceptable to submit incomplete = content to a wiki, whereas it may not feel the same for a 'website'. I can= assure you that there is plenty of content on ocaml.org that could be impr= oved (cf the tutorials section [1]) and in any case, having a lot of incomp= lete content on the internet is exactly one of the things you describe as a= problem (finding outdated/incorrect information). Every other point you r= aise is already catered for by the current set up of ocaml.org. Some speci= fic things I'd like to highlight are: - The PR process already works for (large) code bases so it seems odd to cl= aim that such a system may not work for written content. People can even go= through that process entirely in their browser if they wish. - Discussions happen on PRs, which are based on specific issues. Everyone p= articipating gets email notifications and can keep up on (a) just the thing= s they're discussing or (b) can follow the whole repo. This isn't really m= uch different to a 'talk' page on a wiki and latency only comes down to a (= usually busy) human, not the software. - The questions you ask yourself as a contributor are true of any submissio= n to pretty much anything on the internet. As ocaml.org gets approx 7k hits= per week and people are responsive in the PRs, I'd say all three of your q= uestions are answered with a 'yes'. In general I disagree with the idea that wikis (specifically) are part of a= thriving ecosystem of a language. Ruby-lang.org has no wiki but anyone ca= n submit a PR to the site itself [2]. Python.org does *not* allow such cha= nges to it's main site, therefore they do have a wiki for 'user generated' = content [3]. Both are successful languages with very large user bases. I = also had a quick look at Erlang where there's no wiki nor the ability to ch= ange the website and Haskell just has a wiki, as I'm sure everyone here kno= ws. The important thing for a thriving community is that it has places whe= re it can gather and share knowledge. For OCaml, a list of those places ca= n be found at http://ocaml.org/community/ and the site's content itself can= be improved by anyone. I have a question for you (and anyone else interested in this). Why do you= feel that ocaml.org is *not* the right place to put the kind of informatio= n you're describing? I'd love to see some content there on some of the typ= e theory or other such topics. There are even great blog posts by others t= hat I'd like to import as articles e.g Polymorphism for beginners [4]. If you (or anyone) is not using the site, please say why and we can collect= ively work to improve it. [1] http://ocaml.org/learn/tutorials/ [2] https://github.com/ruby/www.ruby-lang.org/pulls [3] https://wiki.python.org [4] http://roscidus.com/blog/blog/2013/12/20/polymorphism-for-beginners/ Best wishes, Amir On 3 Apr 2014, at 15:05, Yotam Barnoy wrote: > OK a lot of heated comments here... >=20 > I think a central wiki is very important, for many reasons.=20 >=20 > Suppose I want to know what my options are for multicore programming, as = I asked a little while ago on this list. Where do I go? I can do a google s= earch, and find some stackoverflow answers relevant to 2008, some websites = with code that may or may not have been maintained -- it's a mess. What I *= want* people to find is the ocaml wiki, which will have a page on different= multicore methods, discussions of their pluses and minuses, and a link to = the proposal for the new multicore runtime.=20 >=20 > Now suppose I want to find out what a good build system is for ocaml. Hon= estly, until I looked at the documentation for ocp-build (yesterday), I had= no idea what the different systems were. I didn't know, for example, that = oasis used ocamlbuild. That's exactly the kind of thing that's perfect to g= o in a wiki. We have so many build systems in ocaml, and no way to compare = them. >=20 > Another application: when we get to documenting the typechecker, a lot of= that code probably relies on understanding some type theory. It's silly (a= nd impractical) to stuff all of that knowledge into the code itself, but ma= kes perfect sense to do so on a wiki (referring to wikipedia where necessar= y). >=20 > None of these ideas are new. Wikis exist for other languages, and they ex= ist for a reason -- they're part of the thriving ecosystem of a language. >=20 > Now regarding previous wiki efforts: There are 1,650 subscribers on the r= /ocaml reddit, and about 2-4 lingering on the page at any one time. Contras= t this to r/haskell's 15,000 subscribers and ~60 users on the page at a tim= e, and you get a sense of the user ratio. If we say only 1/20th of ocaml us= ers are on r/ocaml, we get around 30,000 users in the world (very rough fig= ure, of course). Bottom line: there aren't many ocaml users (yet). Now how = many of these users are active participants in the community? Out of those,= how many feel confident enough to contribute to documentation? Out of thos= e, how many find the time? You quickly whittle it down to very few people. >=20 > This means that any high level documentation/survey/discussion system (ak= a a wiki) needs to be centralized and not fragmented. I didn't even know ab= out the 2 wikis for camlp4 and ocamlbuild. Had I not asked on this list, I = would probably never have found the compiler internals and compiler hacking= wikis. As a contributor, before I contribute to any of those wikis, I ask = myself:=20 > - Is this the right wiki to contribute to?=20 > - Will my effort be wasted because this wiki is really dead?=20 > - Will anyone see my contribution? >=20 > A centralized wiki solves all of these problems. People know where to con= tribute their input. They know it will be seen, precisely because it's cent= ralized. And it builds up momentum, because people see other people contrib= uting, so they feel like contributing as well. By concentrating the user ba= se on one front, you make the most of what you have as well as grow that ba= se, since new users looking into ocaml will find their answers easily. >=20 > Regarding ocaml.org: I would love for there to be a wiki on ocaml.org. Se= riously, that's the best place for it to be. However, it doesn't seem to me= that the process that currently exists for markdown files can suit a wiki-= type repository. Here are the features of a wiki: > - Easily modifiable. This is huge. The barrier to contribution is very lo= w. And while it's not so bad for ocaml.org, I don't see how the PR process = can scale up to many users constantly modifying, and then modifying each ot= hers' modifications. > - Supports discussions. Serious wikis have a discussion tab for every pag= e, where you can discuss what should be on the page itself. This fosters a = back-and-forth exchange of ideas. I don't see how ocaml.org can support thi= s currently. The PR process simply introduces too much latency. > - One can easily build up a hierarchy, or link to other pages. In a wiki,= if I feel that a topic needs expansion, I can just=20 > create a new page serving as a table of contents to smaller topics, and b= ranch out from there. If I need to link to another topic, I just type the t= opic's name the link appears. To what degree does the ocaml.org infrastruct= ure support this kind of ad-hoc restructuring and linking? > - Incomplete content. In a wiki, I don't care if the page I just wrote is= only partially complete. I can lay out the page in pseudocode style, knowi= ng that I (or someone else) can come later and fix up whatever needs fixing= . It's a constantly evolving platform. The PR review process on ocaml.org b= y definition means that you can't really do that. Even if we remove the req= uirement for a page to be 'complete' in some sense of the word (which is un= likely), the very existence of a review process and a PR means that I won't= submit my page until I feel it's ready -- it's a human psychology thing.=20 >=20 > Bottom line: I think it would be a very big positive step for us to have = a central wiki *somewhere*. If it can be done with ocaml.org that's great. = If not, though I'm not crazy about github's wikis (I don't know for example= if they have discussion support, or if they bypass PRs), I think it makes = sense to either have it off of the ocaml/ocaml repository or in an ocaml/oc= aml-wiki repository of its own. This needs to be the main wiki ie. other th= ings like compiler-hacking/compiler-internals etc should be on this wiki, u= nless you deliberately don't want the ocaml community to find your informat= ion (e.g. if it's proprietary). >=20 > I hope that answers some of your questions. >=20 > -Yotam >=20 >=20 > On Thu, Apr 3, 2014 at 7:07 AM, Ashish Agarwal wr= ote: > On Wed, Apr 2, 2014 at 10:20 PM, Yotam Barnoy wro= te: >=20 > Is it possible to turn on the wiki in the OCaml github account? >=20 > For which repo? If you're asking for the "ocaml" repo, the wiki for it sh= ould, if it all, be used only for matters regarding the compiler. >=20 > I'm unsure that's what you're looking for since you make reference to pre= vious requests on this mailing list, which were for for broader documentati= on in general. None of the repos in the OCaml account would make sense for = that. We could create a separate ocaml-wiki repo, which could have this bro= ader purpose. >=20 > But I see virtually no difference in that and the current ocaml.org imple= mentation, which allows to provide documentation in the same markdown synta= x, with the same requirement of a GitHub account. Every ocaml.org page can = be edited in your browser just like a wiki, and new pages can be added dire= ctly from GitHub's code browser. >=20 > The only difference I see is that your change turns into a pull request, = rather than going live automatically. I think this is a good thing. It's ex= actly what is needed to make sure a wiki doesn't wither away into a disorga= nized mess. >=20 > Have you tried ocaml.org for whatever purpose you're thinking? Has it not= met your needs in some way? Let us know. It would be better to accommodate= what you need in ocaml.org, rather than fragmenting content to another sit= e. >=20 >=20