An experimental, unofficial OCaml wiki

Community
1

Hey guys

There’s a lot of stuff that isn’t currently being documented in the OCaml world. Much of it has to do with the ecosystem, what libraries are good, which ones exist, which ones have issues, where to focus
developer attention etc. Awesome OCaml does some of this, but
is hard to maintain via github. Other things that need to be properly documented are compiler internals, easy-find-links to good articles etc. Then there are many things I haven’t even thought of that need to
be documented.

I’m a firm believer in feedback loops and incrementalism: I think once some things are documented, more and more will be as well, and that this will encourage more community growth. In that spirit, I’ve
created a documentation site called ‘OCamlverse’ at https://ocamlverse.github.io to attempt to meet these demands. Again, it’s entirely possible that this will fail - hence the point of calling this an experiment - but I hope it won’t.

Good static content may be copied gradually to www.ocaml.org. There are some guidelines to pay attention to, posted here. Discussion channels for making large changes are in the issues/PRs of the repo, and on the discord server in the #ocamlverse channel.

Now go forth and document stuff!

Q: Why this and not ocaml.org?

A: ocaml.org is the public face of OCaml to the world. It cannot tolerate rapid changes, partial improvements, multiple sections leading to other sections, experimental partial reorganization etc. It needs to look good. OCamlverse prioritizes contents over looks.

Additionally, just about anyone can become a maintainer on OCamlverse. Just follow the contribution guidelines, make small changes as you wish, medium changes with a post to the discussion channels, and large changes using PRs, and try to make this a comprehensive documentation resource for OCaml. Post your github handle here and you too will become a maintainer. I hope it’s clear that the same process cannot work for ocaml.org.

EDIT: The original idea was to use a real wiki, but I’ve since been convinced to switch over to a more git-based workflow, and the updated post reflects that.

10 Likes
2

My experience, and I guess I agree with @gasche on this, is that there is no such thing as “temporary home” for content like this. It’ll stay where it’s made. awesome-ocaml is a particularly striking example of this. It was supposed to be merged into ocaml.org, and it will never be.

If you want better content on ocaml.org, a better way is to lower the barrier to entry for ocaml.org contributions.

3 Likes
3

I definitely think we should do that, but there’s no harm in having another place to contribute stuff while we slowly make it easier to contribute to ocaml.org, which will take some work.

4

There’s a good case to be made for having both formal documentation and informal documentation. If someone wants to braindump about something no one else knows, then they can put it in a wiki page and if people see fit to edit it then it gets better. Maybe later it’s added to the formal documentation. Whereas any kind of very official documentation will need more thought and editing to get it published, and will likely have less content because of it.

1 Like
5

I should be more specific. I think good, static content could move to ocaml.org. It’s not clear that ocaml.org can handle dynamic content, such as what awesome-ocaml has, simply because the primary purpose of ocaml.org is to be a good-looking gateway to the language.

6

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.

7

@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
8

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
9

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).

10

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.

11

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.

12

FYI I added a link to edit each page. It’s not pretty, but it does the job.

1 Like
13

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
14

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:

  1. Over the long run, we probably need ocaml.org, the main OCaml documentation, etc., to be in very good shape.
  2. 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. :smiley:

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
15

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

16

@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
17

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.

18

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
19

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
20

Update: ocamlverse now includes a shiny new search bar. Hopefully this will increase usability.

3 Likes