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 7EC217F89E for ; Thu, 3 Apr 2014 19:52:46 +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: AlYEAEyfPVODbwiXgWdsb2JhbABYg0GrBplNgR8WDgEBFiYogiUBAQEDARgxJQsFCwsYFQEBFyE2BhMUB4dKAwkIBAnHVw1Xhl8XiUaDEYE4EQEdMwcKCAGDEYEUBJZugyGLOwOIfYFqBxc X-IPAS-Result: AlYEAEyfPVODbwiXgWdsb2JhbABYg0GrBplNgR8WDgEBFiYogiUBAQEDARgxJQsFCwsYFQEBFyE2BhMUB4dKAwkIBAnHVw1Xhl8XiUaDEYE4EQEdMwcKCAGDEYEUBJZugyGLOwOIfYFqBxc X-IronPort-AV: E=Sophos;i="4.97,788,1389740400"; d="scan'208";a="55453676" 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 19:52:44 +0200 X-Cam-AntiVirus: no malware found X-Cam-ScannerInfo: http://www.cam.ac.uk/cs/email/scanner/ Received: from host81-149-212-230.in-addr.btopenworld.com ([81.149.212.230]:17083 helo=[10.0.1.17]) 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 1WVloh-0003lx-Yd (Exim 4.82_3-c0e5623) (return-path ); Thu, 03 Apr 2014 18:52:44 +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 18:52:42 +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 On 3 Apr 2014, at 17:44, Yotam Barnoy wrote: > Thank you for that comparison, Amir. I actually think it's very instructi= ve to look at the difference between www.ruby-lang.org and wiki.python.org.= Ruby (as a community) seems to have stuck with the current approach of oca= ml.org, while python has an extensible wiki. As a result, python has a much= deeper, richer coverage of articles. Just look at https://wiki.python.org/= moin/UsefulModules or https://wiki.python.org/moin/Applications for example= s. Giving users a centralized, free-form avenue to collect knowledge can be= very effective. Having the information accessible in one location means th= at the information is not ephemeral, and that users can find it whenever th= ey want to. >=20 > ocaml.org currently doesn't provide that avenue. You're ascribing the coverage/depth/richness/etc of articles to the fact th= at Python has a wiki but there's actually no way to know if this is really = true. That it's wiki may have had very little to do with it. My point in = using these examples was that Python does not allow anyone to edit their ma= in site whereas Ruby does, hence it would appear that the the Ruby communit= y didn't feel the need to create one. That Ruby doesn't have a wiki hasn't= diminished it's popularity or the ability of people to learn about it and = there are lots (and lots) of resources on the web. Just because they're no= t under 'ruby-lang' does not make them ephemeral. > First of all, the hierarchy of articles is flat. All of the articles are = lumped together under the heading 'tutorials' when that label doesn't neces= sarily fit many of them. I would much rather see a 'Knowledge Base' area, w= ith articles organized by hierarchies with many-to-many mappings of levels = to articles. Second, think of how the 'Useful Modules' python article start= ed out: it was probably pretty empty to begin with, and slowly built up ove= r time as more users contributed. We need an avenue for knowledge that accu= mulates gradually. A 'compiler internals' article will start out mostly emp= ty, as nobody has the time to cover all of it, but it'll fill up over time.= =20 As mentioned before, if the current structure doesn't seem to be working, t= hen it should improve. There's absolutely no rule which says items must li= ve under 'tutorials' and as mentioned, this part of the site is in need of = attention anyway. Also, we don't need to speculate about the page you link to. The first com= mit is at: https://wiki.python.org/moin/UsefulModules?action=3Drecall&rev= =3D1 (login required - spoiler: it started off with 14 entries in 2005 - th= ere are now around 88 entries inc links to elsewhere). Please be aware tha= t the entire ocaml.org site would also have started out page by page in a s= imilar fashion. For example the meetings page [1] is pretty basic but over= time it could become a great resource by accumulating ical event feeds, re= ports, etc. The videos and media page [2] is certainly not 'complete' eith= er but has the potential to put lots more information in front of the thous= ands of visitors the site gets. Whether it's a wiki or a static site, cont= ent still needs curation and building features means it can happen automati= cally. [1] http://ocaml.org/meetings/ [2] http://ocaml.org/community/media.html > Now, I've started implementing a 'Kowledge Base' article under 'Docs', on= the site, but this is currently a mostly empty article with little informa= tion, and I don't know if you'll want to publish it. So Ashish's suggestion= of using the github wiki makes more sense, although really, my ideal would= be something like a 'wiki.ocaml.org', where the wiki is a proper wikimedia= -style wiki, much like wiki.python.org or wiki.xenproject.org. >=20 > In my opinion, there's room for both the structured articles currently on= ocaml.org and a less rigid, evolving centralized wiki. We have the former,= but not the latter. Xen Project is another place where users cannot edit the site itself, so th= e wiki is where user input goes.=20=20 Overall, I get the feeling that your arguments start with the fact that you= want a wiki but the things you state in support of it are just as applicab= le to the current site. The one thing that does stand out is the ability t= o create work-in-progress content to share with others. I like Ashish's su= ggestion of using the github wiki and as he pointed out, you (or anyone) ca= n immediately begin putting content there, structuring it however you feel = appropriate.=20 Best wishes, Amir >=20 >=20 >=20 >=20 > On Thu, Apr 3, 2014 at 11:52 AM, Amir Chaudhry wrote: > Thanks for taking the time to explain your thoughts. >=20 > 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 >=20 > I agree that the above two things are important but imho you haven't spec= ifically explained why a *wiki* is the right solution. The one point that = stands out is that it may feel more socially acceptable to submit incomplet= e content to a wiki, whereas it may not feel the same for a 'website'. I c= an assure you that there is plenty of content on ocaml.org that could be im= proved (cf the tutorials section [1]) and in any case, having a lot of inco= mplete content on the internet is exactly one of the things you describe as= a problem (finding outdated/incorrect information). Every other point you= raise is already catered for by the current set up of ocaml.org. Some spe= cific things I'd like to highlight are: >=20 > - The PR process already works for (large) code bases so it seems odd to = claim that such a system may not work for written content. People can even = go through that process entirely in their browser if they wish. >=20 > - Discussions happen on PRs, which are based on specific issues. Everyone= participating gets email notifications and can keep up on (a) just the thi= ngs they're discussing or (b) can follow the whole repo. This isn't really= much different to a 'talk' page on a wiki and latency only comes down to a= (usually busy) human, not the software. >=20 > - The questions you ask yourself as a contributor are true of any submiss= ion to pretty much anything on the internet. As ocaml.org gets approx 7k hi= ts per week and people are responsive in the PRs, I'd say all three of your= questions are answered with a 'yes'. >=20 > 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 = can submit a PR to the site itself [2]. Python.org does *not* allow such c= hanges 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 = change the website and Haskell just has a wiki, as I'm sure everyone here k= nows. The important thing for a thriving community is that it has places w= here it can gather and share knowledge. For OCaml, a list of those places = can be found at http://ocaml.org/community/ and the site's content itself c= an be improved by anyone. >=20 > I have a question for you (and anyone else interested in this). Why do y= ou feel that ocaml.org is *not* the right place to put the kind of informat= ion you're describing? I'd love to see some content there on some of the t= ype theory or other such topics. There are even great blog posts by others= that I'd like to import as articles e.g Polymorphism for beginners [4]. >=20 > If you (or anyone) is not using the site, please say why and we can colle= ctively work to improve it. >=20 > [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/ >=20 > Best wishes, > Amir >=20 >=20 > On 3 Apr 2014, at 15:05, Yotam Barnoy wrote: >=20 > > OK a lot of heated comments here... > > > > I think a central wiki is very important, for many reasons. > > > > Suppose I want to know what my options are for multicore programming, a= s I asked a little while ago on this list. Where do I go? I can do a google= search, and find some stackoverflow answers relevant to 2008, some website= s 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 differe= nt multicore methods, discussions of their pluses and minuses, and a link t= o the proposal for the new multicore runtime. > > > > Now suppose I want to find out what a good build system is for ocaml. H= onestly, until I looked at the documentation for ocp-build (yesterday), I h= ad no idea what the different systems were. I didn't know, for example, tha= t oasis used ocamlbuild. That's exactly the kind of thing that's perfect to= go in a wiki. We have so many build systems in ocaml, and no way to compar= e them. > > > > Another application: when we get to documenting the typechecker, a lot = of that code probably relies on understanding some type theory. It's silly = (and impractical) to stuff all of that knowledge into the code itself, but = makes perfect sense to do so on a wiki (referring to wikipedia where necess= ary). > > > > None of these ideas are new. Wikis exist for other languages, and they = exist for a reason -- they're part of the thriving ecosystem of a language. > > > > 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. Contr= ast this to r/haskell's 15,000 subscribers and ~60 users on the page at a t= ime, and you get a sense of the user ratio. If we say only 1/20th of ocaml = users are on r/ocaml, we get around 30,000 users in the world (very rough f= igure, of course). Bottom line: there aren't many ocaml users (yet). Now ho= w many of these users are active participants in the community? Out of thos= e, how many feel confident enough to contribute to documentation? Out of th= ose, how many find the time? You quickly whittle it down to very few people. > > > > This means that any high level documentation/survey/discussion system (= aka a wiki) needs to be centralized and not fragmented. I didn't even know = about 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 hacki= ng wikis. As a contributor, before I contribute to any of those wikis, I as= k myself: > > - Is this the right wiki to contribute to? > > - Will my effort be wasted because this wiki is really dead? > > - Will anyone see my contribution? > > > > A centralized wiki solves all of these problems. People know where to c= ontribute their input. They know it will be seen, precisely because it's ce= ntralized. And it builds up momentum, because people see other people contr= ibuting, so they feel like contributing as well. By concentrating the user = base on one front, you make the most of what you have as well as grow that = base, since new users looking into ocaml will find their answers easily. > > > > Regarding ocaml.org: I would love for there to be a wiki on ocaml.org. = Seriously, 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 wik= i-type repository. Here are the features of a wiki: > > - Easily modifiable. This is huge. The barrier to contribution is very = low. And while it's not so bad for ocaml.org, I don't see how the PR proces= s can scale up to many users constantly modifying, and then modifying each = others' modifications. > > - Supports discussions. Serious wikis have a discussion tab for every p= age, 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 t= his currently. The PR process simply introduces too much latency. > > - One can easily build up a hierarchy, or link to other pages. In a wik= i, if I feel that a topic needs expansion, I can just > > create a new page serving as a table of contents to smaller topics, and= branch out from there. If I need to link to another topic, I just type the= topic's name the link appears. To what degree does the ocaml.org infrastru= cture 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, kno= wing that I (or someone else) can come later and fix up whatever needs fixi= ng. It's a constantly evolving platform. The PR review process on ocaml.org= by definition means that you can't really do that. Even if we remove the r= equirement for a page to be 'complete' in some sense of the word (which is = unlikely), 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. > > > > Bottom line: I think it would be a very big positive step for us to hav= e 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 examp= le if they have discussion support, or if they bypass PRs), I think it make= s sense to either have it off of the ocaml/ocaml repository or in an ocaml/= ocaml-wiki repository of its own. This needs to be the main wiki ie. other = things like compiler-hacking/compiler-internals etc should be on this wiki,= unless you deliberately don't want the ocaml community to find your inform= ation (e.g. if it's proprietary). > > > > I hope that answers some of your questions. > > > > -Yotam > > > > > > On Thu, Apr 3, 2014 at 7:07 AM, Ashish Agarwal = wrote: > > On Wed, Apr 2, 2014 at 10:20 PM, Yotam Barnoy w= rote: > > > > Is it possible to turn on the wiki in the OCaml github account? > > > > For which repo? If you're asking for the "ocaml" repo, the wiki for it = should, if it all, be used only for matters regarding the compiler. > > > > I'm unsure that's what you're looking for since you make reference to p= revious requests on this mailing list, which were for for broader documenta= tion in general. None of the repos in the OCaml account would make sense fo= r that. We could create a separate ocaml-wiki repo, which could have this b= roader purpose. > > > > But I see virtually no difference in that and the current ocaml.org imp= lementation, which allows to provide documentation in the same markdown syn= tax, with the same requirement of a GitHub account. Every ocaml.org page ca= n be edited in your browser just like a wiki, and new pages can be added di= rectly from GitHub's code browser. > > > > 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 = exactly what is needed to make sure a wiki doesn't wither away into a disor= ganized mess. > > > > Have you tried ocaml.org for whatever purpose you're thinking? Has it n= ot met your needs in some way? Let us know. It would be better to accommoda= te what you need in ocaml.org, rather than fragmenting content to another s= ite. > > > > >=20 >=20