[Caml-list] Activating wiki on ocaml github

[Caml-list] Activating wiki on ocaml github

[Yotam Barnoy]

[-- Attachment #1: Type: text/plain, Size: 181 bytes --]

Is it possible to turn on the wiki in the OCaml github account? It would be
nice to have a central wiki (something which has been discussed on and off
in previous threads).

-Yotam

[-- Attachment #2: Type: text/html, Size: 224 bytes --]

Re: [Caml-list] Activating wiki on ocaml github

[Gabriel Scherer]

Color me unconvinced. My experience with wikis has been mild at best.
There exist wikis for Camlp4 and Ocamlbuild (
http://brion.inria.fr/gallium/index.php/Camlp4 ,
http://brion.inria.fr/gallium/index.php/Ocamlbuild ) that have seen
little contributions outside the core maintainers, and the content is
often ignored as it is not part of the official manual.

The wiki for the ocaml-hacker-group is probably a good place to put
meeting-specific information, but I don't believe it is a good
long-term place for documentation of the compiler internals. If the
documentation need to be synchronized with the compiler's evolution, I
suspect the best place to put it would be either along the compiler.

Alain's in-code documentation of the parsetree has done a lot of good
and will continue to do so in the future. I'm unconvinced peole would
get the same benefits out of an external wiki.

(On the other hand, formulating documentation as in-code comments does
impose some form restrictions on how to formulate things. I think this
is actually a good thing as it gives more structure.)

On Thu, Apr 3, 2014 at 4:20 AM, Yotam Barnoy <yotambarnoy@gmail.com> wrote:
> Is it possible to turn on the wiki in the OCaml github account? It would be
> nice to have a central wiki (something which has been discussed on and off
> in previous threads).
>
> -Yotam

Re: [Caml-list] Activating wiki on ocaml github

[Daniel Bünzli]

Le jeudi, 3 avril 2014 à 11:16, Gabriel Scherer a écrit :
> Color me unconvinced. My experience with wikis has been mild at best.
> There exist wikis for Camlp4 and Ocamlbuild (
> http://brion.inria.fr/gallium/index.php/Camlp4 ,
> http://brion.inria.fr/gallium/index.php/Ocamlbuild ) that have seen
> little contributions outside the core maintainers, and the content is
> often ignored as it is not part of the official manual.

Yes terrible idea. Though I'd say that's not exactly the same case as we have here. These wiki were created because the creator of these tools refused to write proper/good documentation and said let's "crowd source" the documentation to a wiki, a behaviour that should immediately raise red flags.  
  
> If the documentation need to be synchronized with the compiler's evolution, I
> suspect the best place to put it would be either along the compiler.

The real answer seems to be: literate programming. Maybe more realistically ocamldoc'ing the interfaces and writing cross-referenced [1] additional sections in there at the end of the files could be a good start.

Best,

Daniel

[1] ocamldoc's link syntax combined with its xref syntax allows to author text with very precise references see: http://caml.inria.fr/pub/docs/manual-ocaml-4.01/ocamldoc.html#sss:crossref

Re: [Caml-list] Activating wiki on ocaml github

[Jeremy Yallop]

On 3 April 2014 10:16, Gabriel Scherer <gabriel.scherer@gmail.com> wrote:
> The wiki for the ocaml-hacker-group is probably a good place to put
> meeting-specific information, but I don't believe it is a good
> long-term place for documentation of the compiler internals.

Agreed.  It's for that reason that we have two separate wikis, one for
the compiler hacking group

  https://github.com/ocamllabs/compiler-hacking/wiki

and one for the compiler internals

  https://github.com/ocamllabs/ocaml-internals/wiki

Re: [Caml-list] Activating wiki on ocaml github

[Ashish Agarwal]

[-- Attachment #1: Type: text/plain, Size: 1391 bytes --]

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, 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.org page
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.

[-- Attachment #2: Type: text/html, Size: 2128 bytes --]

Re: [Caml-list] Activating wiki on ocaml github

[Yotam Barnoy]

[-- Attachment #1: Type: text/plain, Size: 7073 bytes --]

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 <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" 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.
>
>

[-- Attachment #2: Type: text/html, Size: 8910 bytes --]

Re: [Caml-list] Activating wiki on ocaml github

[Adrien Nader]

Hi,

On Thu, Apr 03, 2014, Yotam Barnoy wrote:
> 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.

I don't want to comment on the other things mentionned in this thread; I
only want to remind that these values cannot be used to extrapolate
anything. 

Probably the main thing (and I'm sure some will disagree with this) is
that haskellers tend to create more "buzz" and be more vocal. As far as
I can tell it's something few ocamlers are interested in doing or
getting the results of (i.e. sudden increases in new people and this can
be quite taxing for people active in the community).

Btw, don't get me wrong: I don't see this as something bad and I wish
ocamlers were a bit better at it but it seems to be mostly fit people.

Btw, the #ocaml IRC channel has gotten much bigger over the years, from
60 to 80 around 5 years ago (I'd have to check logs) to 200 currently.
As a channel operator, I'm happy there isn't too much noise and drama
there (though there have been some for sure) and that I can follow the
channel even at work while this is not the case for some other channels.

-- 
Adrien Nader

Re: [Caml-list] Activating wiki on ocaml github

[Leo White]

> 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).

All of this information should live on ocaml.org.

> 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.

ocaml.org is easiliy modifiable. Just click the link in the corner,
click the edit button and start typing.

> - 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.

ocaml.org uses Github's issue tracking and pull request system which is well suited for
discussions of changes to content, including supporting inline comments
on pull requests.

> - 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.org infrastructure support
> this kind of ad-hoc restructuring and linking?

If you wish to add a new page or move some things around then just
submit a pull request.

> - 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.

ocaml.org is full of incomplete content :). I'm also not sure that an
argument based on the idea that people won't submit content until it is
ready is a particularly strong one. Besides, some people, myself
included, are more likely to submit things to places if they think their
changes will be looked over by someone, rather than blindly accepted
glaring inaccuracies and all.

> 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).

Bottom line: just use ocaml.org. People have put a lot of effort into
making it easy to submit content, and are even willing to provide some
maintainence of that content. Obviously the system could be improved,
but I think suggestions/pull requests to improve ocaml.org would be more
useful than creating yet another place for OCaml information.

Regards,

Leo

Re: [Caml-list] Activating wiki on ocaml github

[Ashish Agarwal]

[-- Attachment #1: Type: text/plain, Size: 9858 bytes --]

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 <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 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 <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" 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.
>>
>>
>

[-- Attachment #2: Type: text/html, Size: 12741 bytes --]

Re: [Caml-list] Activating wiki on ocaml github

[Amir Chaudhry]

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.org that 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 <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 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.org infrastructure 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 <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" 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.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 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.
> 
> 

Re: [Caml-list] Activating wiki on ocaml github

[Yotam Barnoy]

[-- Attachment #1: Type: text/plain, Size: 12889 bytes --]

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. 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.

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.

-Yotam



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 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 <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 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 <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" 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.
> >
> >
>
>

[-- Attachment #2: Type: text/html, Size: 15709 bytes --]

Re: [Caml-list] Activating wiki on ocaml github

[Amir Chaudhry]

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 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 <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 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.org that 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 <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 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.org infrastructure 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 <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" 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.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 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.
> >
> >
> 
> 

Re: [Caml-list] Activating wiki on ocaml github

[Yotam Barnoy]

[-- Attachment #1: Type: text/plain, Size: 16120 bytes --]

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 <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
> 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 <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 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 <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 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 <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" 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.
> > >
> > >
> >
> >
>
>

[-- Attachment #2: Type: text/html, Size: 19781 bytes --]

Re: [Caml-list] Activating wiki on ocaml github

[Ashish Agarwal]

[-- Attachment #1: Type: text/plain, Size: 713 bytes --]

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

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.
>

I completely agree. Don't feel restricted by the current structure of the
content. It too can and should evolve.

It seems we're reaching consensus. I'm glad you think the ocaml.org wiki is
a reasonable start. Let's see how it goes. However, this thread isn't
enough to publicize that option. We should add a link in the footer.

[-- Attachment #2: Type: text/html, Size: 1209 bytes --]