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

[Yotam Barnoy <yotambarnoy@gmail.com>]

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