Re: [Caml-list] OCaml wiki

[Siraaj Khandkar <siraaj@khandkar.net>]

Or, it seems one can haz cake and eat it too! :)

https://github.com/jgm/gitit


On Dec 21, 2012, at 10:33 AM, Siraaj Khandkar <siraaj@khandkar.net> wrote:

> +1
> 
> Wiki is a fun concept, but is a complete mess in practice.
> 
> It has some versioning capabilities, but not nearly as sophisticated as a DVCS
> such as Git. Obviously, there're editing capabilities, but not nearly as
> productive as your favorite text editor.
> 
> Why force suboptimal tools on people that are interested in an optimal
> programming language? ;)
> 
> Now, what about the maintainers? How do they even begin to keep track of tiny
> edits to 1000's of wiki pages? Queueing theory to the rescue! A pull request
> queue gives them a chance to audit the contributions in a sane manner (without
> wasting their volunteered time).
> 
> 
> On Dec 20, 2012, at 9:49 PM, Ashish Agarwal <agarwal1975@gmail.com> wrote:
> 
>> A wiki could be good but I strongly encourage any such effort to integrate
>> with ocaml.org, and to carefully weigh the pros and cons. Wikis make
>> contributions easier, but you need someone to keep the content organized
>> and do some basic quality control. Also, the structure of the documentation
>> is not very customizable. The question is whether pushing to a git repo
>> (the current contribution method for ocaml.org) is so much harder (given
>> that we're all programmers after all).
>> 
>> The tutorials page is a good candidate for converting to wiki format, but
>> remember that a wiki is where all this content came from, and it eventually
>> got out of date. We could create wiki.ocaml.org, but then the question is
>> how to make it integrate nicely with the rest of the pages that don't fit
>> the wiki model.
>> 
>> Finally, which wiki software to use? None are very good, and who amongst us
>> is keen to hack into php code. My initial goal for ocaml.org was to use
>> ocsigen and ocsimore, but there is a big upfront cost in getting such a
>> site implemented.
>> 
>> Whatever the community decides, we can support and integrate with ocaml.org.
>> My only strong opinion is please don't build a separate unrelated site,
>> with duplication of effort and and fragmentation of content.
>> 
>> 
>> On Thu, Dec 20, 2012 at 6:50 PM, Wojciech Meyer <wojciech.meyer@gmail.com>wrote:
>> 
>>> Anil Madhavapeddy <anil@recoil.org> writes:
>>> 
>>>> On 20 Dec 2012, at 23:31, Benedikt Meurer <
>>> benedikt.meurer@googlemail.com> wrote:
>>>>> 
>>>>> On Dec 21, 2012, at 0:22 , Anil Madhavapeddy <anil@recoil.org> wrote:
>>>>> 
>>>>>> Personally, I've got mixed feelings about wikis from experience with
>>>>>> previous projects, since they get out of date very rapidly indeed. They
>>>>>> do work well if someone's maintaining it, but if that's the case, why
>>>>>> not just push these tips and guides to the existing ocaml.org site?
>>>>>> 
>>>>>> I'm happy to run a wiki on the OCL infrastructure, but would strongly
>>>>>> prefer contributions to the ocaml.org Git repo with all this good
>>> stuff
>>>>>> instead!  If it really turns out we need a swanky wiki, that can be
>>> arranged
>>>>>> later...
>>>>> 
>>>>> Why not use the wiki provided by Github for the ocaml.org project?
>>>> 
>>>> That works too; Thomas has written a Github Markdown to HTML converter in
>>>> COW [1], and is using that to generate the OPAM website from the Github
>>>> wiki (for the documentation that you see on opam.ocamlpro.com).
>>> 
>>> Yes, we could use github pages as long as they are searchable, I see no
>>> problem with it. I think the biggest advantage of wiki would be that
>>> everything would be in single place and hyperlinked.
>>> 
>>> As for protecting the wiki from being up-date emacswiki [1] is always a
>>> great example that it is possible as long as people maintain their
>>> webpages. Also, I feel that ocaml.org pages on github would be a good
>>> entry point.
>>> 
>>> [1] http://emacswiki.org/
>>> 
>>> -Wojciech

-- 
Siraaj Khandkar
.o.
..o
ooo