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 E2B747F89E for ; Thu, 3 Apr 2014 16:05:31 +0200 (CEST) Received-SPF: None (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of yotambarnoy@gmail.com) identity=pra; client-ip=209.85.216.54; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="yotambarnoy@gmail.com"; x-sender="yotambarnoy@gmail.com"; x-conformance=sidf_compatible Received-SPF: Pass (mail3-smtp-sop.national.inria.fr: domain of yotambarnoy@gmail.com designates 209.85.216.54 as permitted sender) identity=mailfrom; client-ip=209.85.216.54; receiver=mail3-smtp-sop.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 (mail3-smtp-sop.national.inria.fr: no sender authenticity information available from domain of postmaster@mail-qa0-f54.google.com) identity=helo; client-ip=209.85.216.54; receiver=mail3-smtp-sop.national.inria.fr; envelope-from="yotambarnoy@gmail.com"; x-sender="postmaster@mail-qa0-f54.google.com"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AvoEACJqPVPRVdg2eGdsb2JhbABYg0FXuwCIdoEXCBYOARUmKoIlAQEBAwEYKAEbEgwDAQsGBQsiGSEBAREBBQEcBhMUh1ABAwkIoBiMX4MOlwwKGScNZIZSEQEFDIk6gxGCIQqELgSWboFtgTSLOwKDXhgphHoh X-IPAS-Result: AvoEACJqPVPRVdg2eGdsb2JhbABYg0FXuwCIdoEXCBYOARUmKoIlAQEBAwEYKAEbEgwDAQsGBQsiGSEBAREBBQEcBhMUh1ABAwkIoBiMX4MOlwwKGScNZIZSEQEFDIk6gxGCIQqELgSWboFtgTSLOwKDXhgphHoh X-IronPort-AV: E=Sophos;i="4.97,787,1389740400"; d="scan'208";a="55421183" Received: from mail-qa0-f54.google.com ([209.85.216.54]) by mail3-smtp-sop.national.inria.fr with ESMTP/TLS/RC4-SHA; 03 Apr 2014 16:05:30 +0200 Received: by mail-qa0-f54.google.com with SMTP id w8so1709674qac.13 for ; Thu, 03 Apr 2014 07:05:24 -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 :content-type; bh=wOnCJy8kWA+LujQhzEgu0qtVu67eH3uQQzew6IElEGM=; b=OKTu0jT2JbMKC4l/sngfyPQEO9nyrR0rERjkOmmWrlownOJgAj/0mA1gmjz2pFwWbp PoZXpw6Jjz5XZXuZCDUZ4u3vf1G9wx4pEmiLKc/512RXJTdE0AZfIsWURy8vgyWOroVj iYG3ZytL6Z29jhqm/mB0wkqZUNwpFvEC1NFTyipEZu1pfzUpEabFrm8auUhPc0pwDf/U YhgwHGOBKM98JNOe9PUDIMNyULGODRdvxr9Q7DcHRArXtGxkl9p61o/VMkCU/xJIimZ4 srKCSpoPO5RPSB0vdJ+3Odu6YwbiyDhfBQtICgvMiAplWUrAtxORxKjUe83dR0SbR6Ld 1AkQ== X-Received: by 10.224.14.14 with SMTP id e14mr7653028qaa.80.1396533920523; Thu, 03 Apr 2014 07:05:20 -0700 (PDT) MIME-Version: 1.0 Received: by 10.224.213.132 with HTTP; Thu, 3 Apr 2014 07:05:00 -0700 (PDT) In-Reply-To: References: From: Yotam Barnoy Date: Thu, 3 Apr 2014 10:05:00 -0400 Message-ID: To: Ocaml Mailing List Content-Type: multipart/alternative; boundary=60eb69fdf4ef3fec8e04f623e41c Subject: Re: [Caml-list] Activating wiki on ocaml github --60eb69fdf4ef3fec8e04f623e41c Content-Type: text/plain; charset=ISO-8859-1 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. > > --60eb69fdf4ef3fec8e04f623e41c Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable
OK a lot of heated= comments here...

I think a central wiki is very importan= t, 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 d= o I go? I can do a google search, and find some stackoverflow answers relev= ant to 2008, some websites with code that may or may not have been maintain= ed -- it's a mess. What I *want* people to find is the ocaml wiki, whic= h will have a page on different multicore methods, discussions of their plu= ses 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= 9;t know, for example, that oasis used ocamlbuild. That's exactly the k= ind of thing that's perfect to go in a wiki. We have so many build syst= ems in ocaml, and no way to compare them.

Another application: when we get to documenting the typechec= ker, 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 co= de itself, but makes perfect sense to do so on a wiki (referring to wikiped= ia where necessary).

None of these ideas are new. Wikis exist for other lang= uages, and they exist for a reason -- they're part of the thriving ecos= ystem of a language.

Now regarding previous wi= ki 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 1= 5,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 conf= ident enough to contribute to documentation? Out of those, how many find th= e time? You quickly whittle it down to very few people.

This means that any high level documentation/survey/discussi= on system (aka a wiki) needs to be centralized and not fragmented. I didn&#= 39;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 th= ose wikis, I ask myself:
- Is this the right wiki to contribute to?
- Will my effort be wasted b= ecause 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 beca= use it's centralized. And it builds up momentum, because people see oth= er people contributing, so they feel like contributing as well. By concentr= ating the user base on one front, you make the most of what you have as wel= l as grow that base, since new users looking into ocaml will find their ans= wers easily.

Regarding ocaml.org: I wou= ld 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 ver= y 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 con= stantly 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 foster= s 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 w= iki, if I feel that a topic needs expansion, I can just
create a new pa= ge serving as a table of contents to smaller topics, and branch out from th= ere. If I need to link to another topic, I just type the topic's name t= he link appears. To what degree does the ocaml= .org infrastructure support this kind of ad-hoc restructuring and linki= ng?
- 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 styl= e, knowing that I (or someone else) can come later and fix up whatever need= s fixing. It's a constantly evolving platform. The PR review process on= ocaml.org by definition means that you ca= n'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 pag= e until I feel it's ready -- it's a human psychology thing.

Bottom line: I think it would be a very big positive step fo= r us to have a central wiki *somewhere*. If it can be done with ocaml.org that's great. If not, though I'm no= t 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 eith= er have it off of the ocaml/ocaml repository or in an ocaml/ocaml-wiki repo= sitory of its own. This needs to be the main wiki ie. other things like com= piler-hacking/compiler-internals etc should be on this wiki, unless you del= iberately 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 <= agarwal1975@gmai= l.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" repo, the wiki for it should, if it all, b= e used only for matters regarding the compiler.

I'm unsure that's what you're looking for since you make refere= nce to previous requests on this mailing list, which were for for broader d= ocumentation 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 hav= e this broader purpose.

But I see virtually no difference in that and the curre= nt ocaml.org implementat= ion, which allows to provide documentation in the same markdown syntax, wit= h 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 directly from GitHub's code br= owser.

The only difference I see is that your change turns int= o a pull request, rather than going live automatically. I think this is a g= ood 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 m= et your needs in some way? Let us know. It would be better to accommodate w= hat you need in ocaml.org, rather than fragmenting content to another site.


--60eb69fdf4ef3fec8e04f623e41c--