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