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

[Leo White <lpw25@cam.ac.uk>]

> 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