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 mail2-relais-roc.national.inria.fr (mail2-relais-roc.national.inria.fr [192.134.164.83]) by sympa.inria.fr (Postfix) with ESMTPS id 77C037F89E for ; Thu, 3 Apr 2014 20:10:51 +0200 (CEST) Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of yotambarnoy@gmail.com) identity=pra; client-ip=209.85.216.170; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="yotambarnoy@gmail.com"; x-sender="yotambarnoy@gmail.com"; x-conformance=sidf_compatible Received-SPF: Pass (mail2-smtp-roc.national.inria.fr: domain of yotambarnoy@gmail.com designates 209.85.216.170 as permitted sender) identity=mailfrom; client-ip=209.85.216.170; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="yotambarnoy@gmail.com"; x-sender="yotambarnoy@gmail.com"; x-conformance=sidf_compatible; x-record-type="v=spf1" Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of postmaster@mail-qc0-f170.google.com) identity=helo; client-ip=209.85.216.170; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="yotambarnoy@gmail.com"; x-sender="postmaster@mail-qc0-f170.google.com"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: Au4EAA2jPVPRVdiqeGdsb2JhbABYDoMzV7sGiHaBFwgWDgEVJiqCJQEBAQMBGAIBJQEIExILAQMBCwYFCwMKFQEBCQ4hAQERAQUBHAYTFAeHSQEDCQgNoBCMX4MOlw4KGScNZIZSEQEFDIk6gxGBOBEBTAQHCggBhCUElm6BbYE0izsCAYNdGCmCboEwXCGBLgcX X-IPAS-Result: Au4EAA2jPVPRVdiqeGdsb2JhbABYDoMzV7sGiHaBFwgWDgEVJiqCJQEBAQMBGAIBJQEIExILAQMBCwYFCwMKFQEBCQ4hAQERAQUBHAYTFAeHSQEDCQgNoBCMX4MOlw4KGScNZIZSEQEFDIk6gxGBOBEBTAQHCggBhCUElm6BbYE0izsCAYNdGCmCboEwXCGBLgcX X-IronPort-AV: E=Sophos;i="4.97,788,1389740400"; d="scan'208";a="66287094" Received: from mail-qc0-f170.google.com ([209.85.216.170]) by mail2-smtp-roc.national.inria.fr with ESMTP/TLS/RC4-SHA; 03 Apr 2014 20:10:48 +0200 Received: by mail-qc0-f170.google.com with SMTP id x13so2310473qcv.15 for ; Thu, 03 Apr 2014 11:10:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc:content-type; bh=6346KZkGQVFVJEOjfL9dLxmU/quycdYeNt1hHLqXIVw=; b=wAX4hGgw66EHoF6PWBKd1XibZPa3+aYDx7Toz6N4QyDm5isijgtpOsg6SCOB0fMAkl kY2aHoYOuQUrWoxZv1/T3i1HpWKLX+NWNwWKS6yq0AwYMCBtN+Nv64I8KcHEhMxRTsbJ FgJ70Y35Li5iWTBdIc9gc1C4KxljpoTny0k15wHNV/cAoUhOez5wDmSoJzwoxms87vlj WdlgCVFcsl9Ebi17pA+K9tI/CzBMTo/AYm4jNyfM+5H3vS+6M4lQgmUVdNrprYa1cgWt UUnywEPvqnWtxLcDHgHQnsgVdPEILcdPON8WMLQLsaPYGfp3bWMrdmbB1g2iWRG00FSp DBOA== X-Received: by 10.140.82.167 with SMTP id h36mr8733716qgd.51.1396548647077; Thu, 03 Apr 2014 11:10:47 -0700 (PDT) MIME-Version: 1.0 Received: by 10.224.213.132 with HTTP; Thu, 3 Apr 2014 11:10:26 -0700 (PDT) In-Reply-To: References: From: Yotam Barnoy Date: Thu, 3 Apr 2014 14:10:26 -0400 Message-ID: To: Amir Chaudhry Cc: Ocaml Mailing List Content-Type: multipart/alternative; boundary=001a11c120ce054ca004f6275214 Subject: Re: [Caml-list] Activating wiki on ocaml github --001a11c120ce054ca004f6275214 Content-Type: text/plain; charset=ISO-8859-1 I admit that the boundary between a wiki and the current site is not a clear one. I'll start using the ocaml.org wiki and we'll see how it goes from there. I'd also like to encourage everybody else to use the same wiki if you have wiki-compatible information to store (that you were going to store somewhere other than ocaml.org). -Yotam On Thu, Apr 3, 2014 at 1:52 PM, Amir Chaudhry wrote: > > On 3 Apr 2014, at 17:44, Yotam Barnoy wrote: > > > Thank you for that comparison, Amir. I actually think it's very > instructive 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 ocaml.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 examples. Giving users a > centralized, free-form avenue to collect knowledge can be very effective. > Having the information accessible in one location means that the > information is not ephemeral, and that users can find it whenever they want > to. > > > > ocaml.org currently doesn't provide that avenue. > > You're ascribing the coverage/depth/richness/etc of articles to the fact > that 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 main site whereas Ruby does, hence it would appear that the the Ruby > community 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 not 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 > necessarily fit many of them. I would much rather see a 'Knowledge Base' > area, with articles organized by hierarchies with many-to-many mappings of > levels to articles. Second, think of how the 'Useful Modules' python > article started out: it was probably pretty empty to begin with, and slowly > built up over time as more users contributed. We need an avenue for > knowledge that accumulates gradually. A 'compiler internals' article will > start out mostly empty, as nobody has the time to cover all of it, but > it'll fill up over time. > > As mentioned before, if the current structure doesn't seem to be working, > then it should improve. There's absolutely no rule which says items must > live 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 > commit is at: > https://wiki.python.org/moin/UsefulModules?action=recall&rev=1 (login > required - spoiler: it started off with 14 entries in 2005 - there are now > around 88 entries inc links to elsewhere). Please be aware that the entire > ocaml.org site would also have started out page by page in a similar > fashion. For example the meetings page [1] is pretty basic but over time > it could become a great resource by accumulating ical event feeds, reports, > etc. The videos and media page [2] is certainly not 'complete' either but > has the potential to put lots more information in front of the thousands of > visitors the site gets. Whether it's a wiki or a static site, content > still needs curation and building features means it can happen > automatically. > > [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 > information, 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. > > > > 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 > the wiki is where user input goes. > > 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 > applicable to the current site. The one thing that does stand out is the > ability to create work-in-progress content to share with others. I like > Ashish's suggestion of using the github wiki and as he pointed out, you (or > anyone) can immediately begin putting content there, structuring it however > you feel appropriate. > > Best wishes, > Amir > > > > > > > > > > > On Thu, Apr 3, 2014 at 11:52 AM, Amir Chaudhry wrote: > > 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 > specifically explained why a *wiki* is the right solution. The one point > that stands 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.orgthat could be improved (cf the tutorials section [1]) and in any case, > having a lot of incomplete 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 specific things I'd like to highlight are: > > > > - 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. > > > > - Discussions happen on PRs, which are based on specific issues. > Everyone participating gets email notifications and can keep up on (a) just > the things 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. > > > > - The questions you ask yourself as a contributor are true of any > submission 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 questions 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 can submit a PR to the site itself [2]. Python.org does *not* allow > such changes 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 knows. The important thing for a thriving community is that > it has places where 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 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 > information you're describing? I'd love to see some content there on some > of the type 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]. > > > > If you (or anyone) is not using the site, please say why and we can > collectively 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... > > > > > > I think a central wiki is very important, for many reasons. > > > > > > 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 search, 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. > > > > > > Now suppose I want to find out what a good build system is for ocaml. > Honestly, 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 go in a wiki. We have so many build systems in ocaml, and no way to > compare 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 > necessary). > > > > > > 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. > Contrast this to r/haskell's 15,000 subscribers and ~60 users on the page > at a time, 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 figure, 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 those, 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 > hacking wikis. As a contributor, before I contribute to any of those wikis, > I ask 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 > contribute their input. They know it will be seen, precisely because it's > centralized. And it builds up momentum, because people see other people > contributing, 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 > wiki-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 > process can scale up to many users constantly modifying, and then modifying > each others' modifications. > > > - Supports discussions. Serious wikis have a discussion tab for every > page, 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 > this 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 > > > 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.orginfrastructure 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, > knowing 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 by definition means that you can't really do that. Even if we > remove the requirement 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 > 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/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 > information (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 > wrote: > > > > > > 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 > previous requests on this mailing list, which were for for broader > documentation 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 broader purpose. > > > > > > But I see virtually no difference in that and the current ocaml.orgimplementation, which allows to provide documentation in the same markdown > syntax, with the same requirement of a GitHub account. Every ocaml.orgpage can be edited in your browser just like a wiki, and new pages can be > added directly 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 disorganized mess. > > > > > > 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 site. > > > > > > > > > > > > --001a11c120ce054ca004f6275214 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable
I admit that the boundary between a wiki and the curr= ent site is not a clear one. I'll start using the ocaml.org wiki and we'll see how it goes from there.

I'd also like to encourage everybody else to use the same wiki if you h= ave wiki-compatible information to store (that you were going to store some= where other than ocaml.org).

-Yotam


On Thu, Apr 3, 2014 at 1:52 PM, Amir Chaudhry <amc79@cam.ac.uk> wrote:

On 3 Apr 2014, at 17:44, Yotam Barnoy <yotambarnoy@gmail.com> wrote:

> Thank you for that comparison, Amir. I actually think it's very in= structive to look at the difference between www.ruby-lang.org and wiki.python.org. Ruby (as a community) seem= s to have stuck with the current approach of ocaml.org, while python has an extensible wiki. As a r= esult, python has a much deeper, richer coverage of articles. Just look at = ht= tps://wiki.python.org/moin/UsefulModules or https://wiki.python.org/moin/A= pplications for examples. Giving users a centralized, free-form avenue = to collect knowledge can be very effective. Having the information accessib= le in one location means that the information is not ephemeral, and that us= ers can find it whenever they want to.
>
> ocaml.org currently= doesn't provide that avenue.

You're ascribing the coverage/depth/richness/etc of articles to t= he fact that Python has a wiki but there's actually no way to know if t= his is really true. =A0That it's wiki may have had very little to do wi= th it. =A0My point in using these examples was that Python does not allow a= nyone to edit their main site whereas Ruby does, hence it would appear that= the the Ruby community didn't feel the need to create one. =A0That Rub= y 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 resour= ces on the web. =A0Just because they're not under 'ruby-lang' d= oes not make them ephemeral.


> First of all, the hierarchy of articles is flat. All of the articles a= re lumped together under the heading 'tutorials' when that label do= esn't necessarily fit many of them. I would much rather see a 'Know= ledge Base' area, with articles organized by hierarchies with many-to-m= any mappings of levels to articles. Second, think of how the 'Useful Mo= dules' python article started out: it was probably pretty empty to begi= n with, and slowly built up over time as more users contributed. We need an= avenue for knowledge that accumulates gradually. A 'compiler internals= ' article will start out mostly empty, as nobody has the time to cover = all of it, but it'll fill up over time.

As mentioned before, if the current structure doesn't seem to be = working, then it should improve. =A0There's absolutely no rule which sa= ys items must live 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. =A0The fir= st commit is at: https://wiki.python.org/moin/Use= fulModules?action=3Drecall&rev=3D1 (login required - spoiler: it st= arted off with 14 entries in 2005 - there are now around 88 entries inc lin= ks to elsewhere). =A0Please be aware that the entire ocaml.org site would also have started out pag= e by page in a similar fashion. =A0For example the meetings page [1] is pre= tty basic but over time it could become a great resource by accumulating ic= al event feeds, reports, etc. =A0The videos and media page [2] is certainly= not 'complete' either but has the potential to put lots more infor= mation in front of the thousands of visitors the site gets. =A0Whether it&#= 39;s a wiki or a static site, content still needs curation and building fea= tures means it can happen automatically.

[1] http://ocaml.o= rg/meetings/
[2] htt= p://ocaml.org/community/media.html


> Now, I've started implementing a 'Kowledge Base' article u= nder 'Docs', on the site, but this is currently a mostly empty arti= cle with little information, and I don't know if you'll want to pub= lish it. So Ashish's suggestion of using the github wiki makes more sen= se, although really, my ideal would be something like a 'wiki.ocaml.org', where the wi= ki is a proper wikimedia-style wiki, much like wiki.python.org or wiki.xenproject.org.
>
> In my opinion, there's room for both the structured articles curre= ntly on ocaml.org and a = less rigid, evolving centralized wiki. We have the former, but not the latt= er.

Xen Project is another place where users cannot edit the site itself,= so the wiki is where user input goes.

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. =A0The one thing that does stand out is the ability= to create work-in-progress content to share with others. =A0I like Ashish&= #39;s suggestion of using the github wiki and as he pointed out, you (or an= yone) can immediately begin putting content there, structuring it however y= ou feel appropriate.

Best wishes,
Amir

>
>
>
>
> On Thu, Apr 3, 2014 at 11:52 AM, Amir Chaudhry <amc79@cam.ac.uk> wrote:
> Thanks for taking the time to explain your thoughts.
>
> I've tried to read carefully and I summarise your main points to b= e:
> (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 specifically explained why a *wiki* is the right solution. =A0The one po= int that stands 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 'w= ebsite'. =A0I can assure you that there is plenty of content on ocaml.org that could be improve= d (cf the tutorials section [1]) and in any case, having a lot of incomplet= e content on the internet is exactly one of the things you describe as a pr= oblem (finding outdated/incorrect information). =A0Every other point you ra= ise is already catered for by the current set up of ocaml.org. =A0Some specific things I'd like= to highlight are:
>
> - 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 ev= en go through that process entirely in their browser if they wish.
>
> - Discussions happen on PRs, which are based on specific issues. Every= one participating gets email notifications and can keep up on (a) just the = things they're discussing or (b) can follow the whole repo. =A0This 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.
>
> - The questions you ask yourself as a contributor are true of any subm= ission to pretty much anything on the internet. As ocaml.org gets approx 7k hits per week and peopl= e are responsive in the PRs, I'd say all three of your questions are an= swered with a 'yes'.
>
> In general I disagree with the idea that wikis (specifically) are part= of a thriving ecosystem of a language. =A0Ruby-lang.org has no wiki but an= yone can submit a PR to the site itself [2]. =A0Python.org does *not* allow= such changes to it's main site, therefore they do have a wiki for '= ;user generated' content [3]. =A0Both are successful languages with ver= y large user bases. =A0I 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 knows. =A0The important thing for a thriving = community is that it has places where it can gather and share knowledge. = =A0For OCaml, a list of those places can 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). =A0Why= do you feel that ocaml.org<= /a> is *not* the right place to put the kind of information you're desc= ribing? =A0I'd love to see some content there on some of the type theor= y or other such topics. =A0There are even great blog posts by others that 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 co= llectively work to improve it.
>
> [1] ht= tp://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/p= olymorphism-for-beginners/
>
> Best wishes,
> Amir
>
>
> On 3 Apr 2014, at 15:05, Yotam Barnoy <yotambarnoy@gmail.com> wrote:
>
> > 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 programm= ing, as 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 w= ebsites with code that may or may not have been maintained -- it's a me= ss. 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, an= d a link to the proposal for the new multicore runtime.
> >
> > Now suppose I want to find out what a good build system is for oc= aml. Honestly, until I looked at the documentation for ocp-build (yesterday= ), I had no idea what the different systems were. I didn't know, for ex= ample, that oasis used ocamlbuild. That's exactly the kind of thing tha= t's perfect to go in a wiki. We have so many build systems in ocaml, an= d no way to compare them.
> >
> > Another application: when we get to documenting the typechecker, = a lot of that code probably relies on understanding some type theory. It= 9;s silly (and impractical) to stuff all of that knowledge into the code it= self, but makes perfect sense to do so on a wiki (referring to wikipedia wh= ere necessary).
> >
> > 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.= Contrast this to r/haskell's 15,000 subscribers and ~60 users on the p= age at a time, 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 (ve= ry rough figure, of course). Bottom line: there aren't many ocaml users= (yet). Now how many of these users are active participants in the communit= y? Out of those, how many feel confident enough to contribute to documentat= ion? Out of those, how many find the time? You quickly whittle it down to v= ery few people.
> >
> > This means that any high level documentation/survey/discussion sy= stem (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 t= his list, I would probably never have found the compiler internals and comp= iler hacking wikis. As a contributor, before I contribute to any of those w= ikis, I ask 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 wher= e to contribute their input. They know it will be seen, precisely because i= t's centralized. And it builds up momentum, because people see other pe= ople contributing, 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.or= g: I would love for there to be a wiki on ocaml.org. Seriously, that's the best place for i= t 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 fe= atures 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 process can scal= e up to many users constantly modifying, and then modifying each others'= ; modifications.
> > - Supports discussions. Serious wikis have a discussion tab for e= very page, where you can discuss what should be on the page itself. This fo= sters a back-and-forth exchange of ideas. I don't see how ocaml.org can support this 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
> > create a new page serving as a table of contents to smaller topic= s, and branch out from there. If I need to link to another topic, I just ty= pe the topic's name the link appears. To what degree does the ocaml.org infrastructure suppor= t this kind of ad-hoc restructuring and linking?
> > - Incomplete content. In a wiki, I don't care if the page I j= ust wrote is only partially complete. I can lay out the page in pseudocode = style, knowing that I (or someone else) can come later and fix up whatever = needs fixing. It's a constantly evolving platform. The PR review proces= s on ocaml.org by defini= tion means that you can't really do that. Even if we remove the require= ment for a page to be 'complete' in some sense of the word (which i= s unlikely), the very existence of a review process and a PR means that I w= on't submit my page until I feel it's ready -- it's a human psy= chology thing.
> >
> > 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, thou= gh 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 info= rmation (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 <agarwal1975@gmail.com> wrote:
> > On Wed, Apr 2, 2014 at 10:20 PM, Yotam Barnoy <yotambarnoy@gmail.com> wrote:
> >
> > Is it possible to turn on the wiki in the OCaml github account? > >
> > For which repo? If you're asking for the "ocaml" re= po, the wiki for it should, if it all, be used only for matters regarding t= he compiler.
> >
> > I'm unsure that's what you're looking for since you m= ake reference to previous requests on this mailing list, which were for for= broader documentation in general. None of the repos in the OCaml account w= ould make sense for that. We could create a separate ocaml-wiki repo, which= could have this broader purpose.
> >
> > But I see virtually no difference in that and the current ocaml.org implementation, which= allows to provide documentation in the same markdown syntax, with the same= requirement of a GitHub account. Every ocaml.org page can be edited in your browser just like a wi= ki, and new pages can be added directly from GitHub's code browser.
> >
> > The only difference I see is that your change turns into a pull r= equest, 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 awa= y into a disorganized mess.
> >
> > Have you tried oca= ml.org for whatever purpose you're thinking? Has it not met your ne= eds in some way? Let us know. It would be better to accommodate what you ne= ed in ocaml.org, rather = than fragmenting content to another site.
> >
> >
>
>


--001a11c120ce054ca004f6275214--