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 D6EC27F89F for ; Thu, 3 Apr 2014 17:52:24 +0200 (CEST) Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of agarwal1975@gmail.com) identity=pra; client-ip=209.85.192.45; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="agarwal1975@gmail.com"; x-sender="agarwal1975@gmail.com"; x-conformance=sidf_compatible Received-SPF: Pass (mail2-smtp-roc.national.inria.fr: domain of agarwal1975@gmail.com designates 209.85.192.45 as permitted sender) identity=mailfrom; client-ip=209.85.192.45; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="agarwal1975@gmail.com"; x-sender="agarwal1975@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-qg0-f45.google.com) identity=helo; client-ip=209.85.192.45; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="agarwal1975@gmail.com"; x-sender="postmaster@mail-qg0-f45.google.com"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AncFADKDPVPRVcAteGdsb2JhbABYgkJ/UQa7AIh2gRcIFg4BFSYqgiUBAQEDARgoARsSCwEDAQsGBQsiGSEBAREBBQEcBhMUh1ABAwkICAWgEIxfgw6XDgoZJw1khlIRAQUMiTqDEYIWBAcKhC4Elm6BbYE0izsCAYNdGCmEeiE X-IPAS-Result: AncFADKDPVPRVcAteGdsb2JhbABYgkJ/UQa7AIh2gRcIFg4BFSYqgiUBAQEDARgoARsSCwEDAQsGBQsiGSEBAREBBQEcBhMUh1ABAwkICAWgEIxfgw6XDgoZJw1khlIRAQUMiTqDEYIWBAcKhC4Elm6BbYE0izsCAYNdGCmEeiE X-IronPort-AV: E=Sophos;i="4.97,787,1389740400"; d="scan'208";a="66265805" Received: from mail-qg0-f45.google.com ([209.85.192.45]) by mail2-smtp-roc.national.inria.fr with ESMTP/TLS/RC4-SHA; 03 Apr 2014 17:52:07 +0200 Received: by mail-qg0-f45.google.com with SMTP id j5so1983421qga.18 for ; Thu, 03 Apr 2014 08:52:06 -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=kN/W8aJfLiMUNye4l2sZJZMmrhqyw6MIqxLo8CyBjH8=; b=z/pMOg2pgsveXm7loBif+vnYcVpxXdMDW3A0itx/HEe2gHkB1qQtDQ5EXRcDczgJT0 OfIdfKOgWhc0Lk6lcBq3UHFx1zNv8rAvV0Gtrqgo4cvVS9HLqZLnt2xsJbIreneVZg5f NkqsblL9t7T6+havE/LEKxdlTHXVK7z4ez3NcCGvsl8h9tIujVSAsNYRdHMaMmPIOCZk DeI4/vW65rnvzjnReACZ+kyLwwG9Jh3R4lCehXDm1S8y63RHhPq7Szf2LWLqA5yRTqkM 3FFQN8vxrKZiYyDiSVkA2aWDDTNWTzlAM1CJuoYzkgPzhqkM6++BJE0OoOZRbcy3IIxA Irpg== X-Received: by 10.224.88.131 with SMTP id a3mr8277439qam.54.1396540326811; Thu, 03 Apr 2014 08:52:06 -0700 (PDT) MIME-Version: 1.0 Received: by 10.229.67.69 with HTTP; Thu, 3 Apr 2014 08:51:46 -0700 (PDT) In-Reply-To: References: From: Ashish Agarwal Date: Thu, 3 Apr 2014 11:51:46 -0400 Message-ID: To: Yotam Barnoy Cc: Ocaml Mailing List Content-Type: multipart/alternative; boundary=001a11c2dac0181cd104f62562e0 Subject: Re: [Caml-list] Activating wiki on ocaml github --001a11c2dac0181cd104f62562e0 Content-Type: text/plain; charset=ISO-8859-1 You mention several features of wikis: - Easily modifiable - Your original proposal was to enable a wiki on GitHub, so almost exactly what ocaml.org already is. If you were proposing a different wiki technology, then this point could be argued, but not if you're asking for a GitHub based wiki. (And if you were proposing a different technology, I'd probably still disagree. I think Markdown is the best syntax we have, and I really like that I can do a pull, modify in the text editor of my choice, then push. I dislike typing content within a browser, unless it is a small change.) - Supports discussions - Again, this also wouldn't be available in the GitHub based wiki you proposed, so ocaml.org is no different on this point. Furthermore, I feel GitHub's issue system addresses this sufficiently. - One can easily build up a hierarchy - Although I consider this a minor point, I accept it is true in the current system. Links in a markdown file within the main part of a GitHub repo do not automatically become clickable. However, they do for markdown pages within the GitHub wiki feature of a repo (see my proposal below). - Incomplete content - I accept your argument on this. It is true that ocaml.org has tried to promote good, complete content. What you're asking for is a place to have incomplete, possibly poorly written content. I see the value in that. Sometimes you just want to write something down, and maybe it'll improve over time or not. Here's an option: add whatever you want to the wiki [1] of the ocaml/ ocaml.org repo (not of ocaml/ocaml, that wouldn't make sense). It is already enabled, and as far as I can tell anyone can edit without a PR. I believe this gives you every feature you're asking for. Once you've added something, we can decide what to do with the content. If you want, we can easily publish it, e.g. to http://ocaml.org/wiki. The exact URL depends on how we want to market this content. Calling it "wiki" will imply to most people that the content is permanent, and I would get confused about how this sections differs from the Tutorials page. Thus, a better choice might be http://ocaml.org/sandbox. Then, it is clear this is scratch work, potentially incomplete, potentially wrong, etc. When content within sandbox is deemed good enough, we move it to Tutorials or other appropriate section. (In fact, some of the current tutorials should go into scratch, as they are quite out of date.) [1] https://github.com/ocaml/ocaml.org/wiki On Thu, Apr 3, 2014 at 10:05 AM, 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. >> >> > --001a11c2dac0181cd104f62562e0 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable
You mention several features of wikis:

= - Easily modifiable - Your original proposal was to enable a wiki on GitHub= , so almost exactly what ocaml.org already= is.=A0If you were proposing a different wiki technology, then this point c= ould be argued, but not if you're asking for a GitHub based wiki. (And = if you were proposing a different technology, I'd probably still disagr= ee. I think Markdown is the best syntax we have, and I really like that I c= an do a pull, modify in the text editor of my choice, then push. I dislike = typing content within a browser, unless it is a small change.)

- Supports discussions - Again, this also wouldn't = be available in the GitHub based wiki you proposed, so ocaml.org is no different on this point. Fur= thermore, I feel GitHub's issue system addresses this sufficiently.

-=A0One can=A0easily build up a hierarchy - Although I consider this= a minor point, I accept it is true in the current system. Links in a markd= own file within the main part of a GitHub repo do not automatically become = clickable. However, they do for markdown pages within the GitHub wiki featu= re of a repo (see my proposal below).

- Incomplete content - I accept your argument on this. = It is true that ocaml.org has tried to pro= mote good, complete content. What you're asking for is a place to have = incomplete, possibly poorly written content. I see the value in that. Somet= imes you just want to write something down, and maybe it'll improve ove= r time or not.

Here's an option: add whatever you want to the wiki= [1] of the ocaml/ocaml.org repo (not of o= caml/ocaml, that wouldn't make sense). It is already enabled, and as fa= r as I can tell anyone can edit without a PR. I believe this gives you ever= y feature you're asking for.

Once you've added something, we can decide what to = do with the content. If you want, we can easily publish it, e.g. to http://ocaml.org/wiki. The exact URL depends= on how we want to market this content. Calling it "wiki" will im= ply to most people that the content is permanent, and I would get confused = about how this sections differs from the Tutorials page. Thus, a better cho= ice might be http://ocaml.org/sandbox<= /a>. Then, it is clear this is scratch work, potentially incomplete, potent= ially wrong, etc. When content within sandbox is deemed good enough, we mov= e it to Tutorials or other appropriate section. (In fact, some of the curre= nt tutorials should go into scratch, as they are quite out of date.)





On Thu, Apr 3, 2014 at 10:05 AM, Yotam Barnoy <yotambarnoy@gmail.com> wrote:
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 oc= aml.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 cur= rently 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 constantly modifying, and then modifying each others' mo= difications.
- 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 restr= ucturing 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 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 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 un= likely), the very existence of a review process and a PR means that I won&#= 39;t submit my page until I feel it's ready -- it's a human psychol= ogy 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 not crazy about github's wikis (I don't know for ex= ample if they have discussion support, or if they bypass PRs), I think it m= akes sense to either have it off of the ocaml/ocaml repository or in an oca= ml/ocaml-wiki repository of its own. This needs to be the main wiki ie. oth= er things like compiler-hacking/compiler-internals etc should be on this wi= ki, 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 <<= a href=3D"mailto:agarwal1975@gmail.com" target=3D"_blank">agarwal1975@gmail= .com> wrote:
=
On Wed, Apr 2, 2014 at 10:20 PM, Yotam Barn= oy <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.



--001a11c2dac0181cd104f62562e0--