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

[Ashish Agarwal <agarwal1975@gmail.com>]

[-- 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 --]