Contribution Guidelines

You want to contribute? Awesome. Here are some important guidelines:

The trickiest part of a wiki is what the organization should be: what should the categories be, and where do you split into pages vs. keeping things as sub-sections on the same page.

Discussions

  • We can discuss details of this wiki either on discord in the #wiki channel, or on discuss/ecosystem with a wiki tag. We don't want to create another forum here — we have enough communication channels.
  • Before you split a page/create a new category/change a page radically, please post on one of the above channels so we can discuss it first.

Goals

  • The driving motivation for this site is to improve the OCaml community. If you're not interested in that goal, please don't join the site.
  • Our goal is to have this wiki be as useful a resource as possible. As as example, we don't just want to list some obscure libraries that aren't used: OPAM can do that too. We want to direct users to the good libraries, give them tips about them, and let the users know if some libraries are deprecated or unmaintained.
  • In terms of the learning category, we want to provide the most useful material to learn up-to-date practices, rather than linking to everything out there despite the quality.
  • Is there a specific limit to the types of content we envision for this wiki? Not really. If you want to have your project documented here, that's fine. If you want to have pages about type theory, that's fine too. Laying out a vision for a new library? Sounds good. Anything in the OCaml universe is fair game as far as we're concerned. Let's just chat about it first in the discussion channels, and try to keep the hierarchy sane and logical.

Tone and attitude

  • Try to be as professional sounding as possible — not in a pretentious way, just try to be neutral.
  • Don't denigrate particular projects or people. Saying a project is unmaintained is fine if it's true — saying it sucks isn't. Reasonable praise is welcome.
  • Accept that people will change your content. A wiki is a living document.
  • Expect people to disagree with you. Defer to the experts and to the site managers.
  • Accept criticism. Even if your contribution is criticized, you need to be able to accept the criticism, learn and adapt.

Categories

  • So far, our main categories are ecosystem, learning, meta, compiler and community.
  • If you want to add a category, please discuss it in the discussion channels first.
  • When creating a link to a page, you should precede the page with the category e.g. [[[ecosystem:Build Systems]]]. If you don't, you'll create the wrong page.

Splitting Pages

  • Regarding splitting pages, our general approach is to think how much you have to write about a particular topic. If it's more than half a page, it might justify its own page. Otherwise, being in a parent topic's page is fine.
  • If you place a topic in a parent page, use a heading of some level (+).
  • We recommend dropping an invisible anchor right after the heading with [[# anchor-name]]. Note that anchors should be lowercase, and should have dashes rather than underscores to separate words. Note also the space after the (#). An anchor lets you link directly to that section with a #anchor after the link.
  • Splitting pages is good for one basic reason: page locks. The more you split up pages, the better the chance you won't clash with another person editing the same page.
  • At the same time, please save and thus release your lock as fast as you can. Wikis let you iterate quickly, so you don't have to make a full change right away.

Syntax

  • Note that wikidot syntax is not the same as mediawiki, or markdown! [https://link.com This is a link] rather than [This is a link](https://link.com). Wiki links are [[[category:Page]]]. Look up the other differences as needed.
  • Don't use advanced stuff. [[toc]] at the top for table of contents is fine (and is highly recommended for pages with multiple headings), but we also want to keep this wiki portable so we can migrate it if need be.
  • There are wikidot to mediawiki converters on github, so conversion isn't a problem.

Copying Content

  • Only copy material rather than link to it (better yet, do both) if you've been granted permission by the author of said material.
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License