I think this is exactly right. We need a place where the content is king – where the looks don’t matter, and we can incrementally work on improving documentation. ocaml.org, as the public face of OCaml to the world, cannot be that place.
@kakadu made an excellent point on IRC, which is that wikis aren’t really necessary nowadays since github provides very similar functionality with its combination of readme.md and links to other markdown documents. I think this may be true, and the advantages of using github’s infrastructure over wikidot’s are plenty. For one thing, wikidot has a different syntax from markdown, and markdown has become the industry standard. For another, not everyone wants a wikidot account, but everyone has a github account. Finally, using github means we’re using git for version control, whereas wikidot has its own weird page-lock and history system.
I briefly considered using github wikis, but I strongly dislike their look, and additionally, github’s robots.txt file prohibits google from indexing any of the wikis.
For these reasons, I’ve made a clone of the wiki on github. Right now I’m still evaluating, but I’m heavily leaning towards this version rather than the wiki version. The repo can be found here or with the shorter path https://git.io/ocamlverse, and is fully usable as is. Additionally, the pretty github pages version is here or at https://git.io/overse.
I really think github changed the rules of the game here. Let me know if you like this version. The benefit of having such a simple system cannot be overstated.
1 Like
Thank you for setting this up @bluddy. I see it has quite a number of content already, nice work!
I however notice some duplicate content from awesome-ocaml (especially in the Ecosystem pages). How do you see the two collaborates? Will ocamlverse eventually supersede awesome-ocaml?
Also, will using github pages solve the indexing issue?
(I also saw your note on documentation best practices section; I’m okay with you putting it inline, perhaps deprecating my repo and pointing it there if needed.)
1 Like
I took most of that from awesome-ocaml so we have a good starting point. I changed some of the categories though and tried to make it more orderly, splitting up into multiple pages where I felt the content justified it.
I see ocamlverse as a community-maintained site, organized for the needs of the community. Awesome ocaml by definition fits into the ‘awesome’ line of sites, and suffers somewhat for adhering to that format. Describing the state of the ecosystem is just one sub-function I foresee for ocamlverse. I’m happy to make just about anyone a maintainer of ocamlverse so that we can have a near-wiki experience, simply one maintained with git and using markdown. Any radical changes should probably be done through the PR process, but small to medium sized ones can be done directly.
The github pages is a bonus – a slightly nicer way of browsing the content that was just too easy to set up. github’s robots.txt allows crawling only of the master branch of a repo (for this reason, ocaml’s ‘trunk’ branch isn’t indexed directly, for example), so we should be covered by that.
Great! I’d be happy to add you to the maintainers and you’re welcome to do that if you want, or I can do it when I get a chance.
In general, anyone who wants to help maintain ocamlverse (even if it’s just to modify something small) can post their github username here and I’ll be glad to add them. Just pay attention to the contribution guidelines (which need to be rewritten a little since it’s no longer a real wiki).
Is there any way to use github pages and the normal github wiki interface? I think having an ‘edit’ button lowers the barrier of entry.
I don’t know of such a way, but maybe someone else does? There’s something about it here. Feel free to join the site (post your github name and I’ll add you) and you can fix this if you wish. Otherwise I’ll take a look later.
In any case, the github interface is fully functional if you follow it from the readme.md at the bottom, and can be edited in the github GUI.
FYI I added a link to edit each page. It’s not pretty, but it does the job.
1 Like
But there is an edit button on ocaml.org !
Look at this article, click on the “pen” button on the top right, you land on the github page in markdown. Click again on the pen button on the top right, you can edit the markdown inline, with previews and instantly make a PR. tada.
1 Like
For some of ocaml.org that’s easier than for other parts. I am now able to contribute to it, but the build process, which was needed to preview some of the content (including the front page), was quite broken until recently. Luckily it is now all working.
I’d say none of this has to be an exclusive or. We can have several sorts of resources, see what sticks. I think that we need to keep two things in mind:
- Over the long run, we probably need ocaml.org, the main OCaml documentation, etc., to be in very good shape.
- There’s nothing wrong with trying a bunch of other stuff to make contributions easier and seeing what works best.
We’re all trying to get the same thing done, even if we have different visions of how to do it.
For myself, I’m trying to concentrate right now on improving the core manual and documentation facilities. Amazingly, several people popped up to help with things like the CSS for the manual at a strategic moment so I’ve not had to do very much. 
At some point after the DocJam, I intend to start thinking about how to simplify ocaml.org to make it easier to contribute to.
Meanwhile, I see nothing wrong with Bluddy trying various things out. Wikis and other user-driven documentation sites sometimes fail horribly and sometimes generate a lot of good content. We’ll see how it goes.
4 Likes
I think this is a great idea, the ocamllex refill example I posted recently is intended to complement the compiler and tools documents but doesn’t really belong with it (It’s a bit long in my view for the actual manual).
In the longer term it feels like this sort of content should be migrated into ocaml.org to provide a one stop shop for good examples, usage and learning. However, I feel there needs to be somewhere for content to mature and ocamlverse is as good a place as any
@bluddy Thanks for setting this up. I think we can relax the view that ocaml.org has to adhere to some higher standard of quality or stability. There is some structure in ocaml.org that is difficult to change (which is not necessarily a bad thing, you can’t have a good design and stable links if people keep re-organizing pages entirely). We have 4 primary landing pages: Learn, Documentation, Community, and Packages. These pages are heavily styled and are not so easy to change (in hindsight, this was perhaps a mistake). If you do change them significantly, it is expected that you have a pretty good grasp of all the content on ocaml.org because they are the gateway to all the content. You can’t just delete items because then there is no link to that content from anywhere. So we would have to review such a PR carefully.
However, you can have a lot of freedom on other pages, which are mostly content, exactly what you want to focus on. For example, OCamlverse’s Learning page is similar to ocaml.org’s Tutorials page, so I think all this content in essentially the exact same format could have been added directly to ocaml.org. A PR for something like this would be accepted easily.
As pointed out, your Learning page is similar to awesome-ocaml, and I long ago proposed that an awesome-ocaml style list of links replace the content of the current Tutorials page. See issue 502.
Just to give one more example, the FAQ page could be improved too. It’s just a list, grouped into some categories. Anyone could add a FAQ or re-group the items. Such a PR would be accepted pretty easily. These pages are very “dynamic” in the sense you’re saying. Only problem is no one has submitted such PRs.
2 Likes
When I tried to submit my first ocaml.org PR recently, I found that the build system was broken. It is now fixed. That said, I suspect it still remains somewhat intimidating to contribute. I’m thinking about ways to improve this.
Well, that’s good to know.
I think we need to think about the design of the Tutorials page. Reason’s Docs page is so very elegant and minimalist, I think we’d do well to learn from that.
Reiterating the position @perry stated above, I don’t think there’s a conflict between ocamlverse and ocaml.org. The goal is to increase documentation contributions, and expose more people to aspects of OCaml they may have not known about. ocamlverse, to me, serves as a very free-form place to do that. Everyone who wants gets merge permission, making it really easy to make small changes and fixes. And most contributions are only one or two clicks away from being visible, meaning that people should hopefully feel they’re making a visible difference. I don’t know if this will really work, but if it does, the increase in contribution level should also percolate over to ocaml.org as well.
In the meantime, I think ocaml.org needs to be made as ‘sexy’ as possible to attract users. Nowadays that also implies that it needs to be lean and minimalist – that’s the popular style nowadays, and unfortunately in the web realm you have to keep up with trends even if they change every couple of years. Again, I think the reason site is a great example of the general concept.
1 Like
Just a note that we’ve migrated OCamlverse away from my github user so multiple people can be admin. Find us at https://ocamlverse.github.io
1 Like
Update: ocamlverse now includes a shiny new search bar. Hopefully this will increase usability.
3 Likes
We just got a nice redesign courtesy of @fallbackusername ! If you haven’t checked ocamlverse out yet, come do so!
In the spirit of ocamlverse and also imitating some success I have seen with github tables for maintaining decentralized data sets, I copied and checked dead links from the ocaml.org’s courses list and placed it here https://gitlab.com/kanishka-azimi/ocaml-courses. I don’t have any interest in being the maintainer of this list over time, but I’m curious to see if this attracts more frequent updates. If it does attract updates, I’ll request to move it into an official ocaml-community github area.
1 Like
I’d be happy to host this on ocamlverse. Feel free to create a PR.
My working theory is the immediate feedback of the Gitlab table + edit in gitlab functionality + narrow scope of data will attract the most updates. I will test it out for about six months. If I get lots of updates, then I will come up with a shell script to fetch this data from this repo and load it into ocamlverse.
1 Like
Looking at OCamlverse’s Help Wanted page, I’d really like to update it with material that’s most relevant to today’s ecosystem:
- What projects could use the most help?
- Which projects have open issues that could be tackled by beginners?