Edit

Contributing

You want to contribute? That’s great. There are just a few rules to follow so we all get along.

Goals

• This site is intended to be a way for people to help improve the OCaml community! (If that’s not for you, this probably isn’t the site you’re looking for.)
• Our goal is to have OCamlverse be as useful a documentation resource as possible.
• Let’s also use OCamlverse to energize and motivate the OCaml community, encouraging further growth!

Discussion channels

• Discussion about this resource happens
  • On discuss.ocaml.org in Ecosystem with the ocamlverse tag: long-term vision and direction
  • On discord in the #ocamlverse channel: quick, responsive discussion about issues.
  • In an issue in this repo: ideas for content, missing pieces
  • In a PR: discussions of a particular change

Tagging pages

Pages should be filed under one of the following tags to be automatically added to the sidebar menu:

• quickstart
• learning
• compiler
• package management
• types
• best practices
• ecosystem
• advanced
• community
• meta

The addition of tags should be reflected in the page.html template.

Tone and attitude

• Contribute to the extent that you know, but feel free to get the ball rolling on content you’re not confident on.
• You can also leave a question in the content itself asking for someone more knowledgable to fill in the gaps.
• Try to be objective and cordial.
• Accept that people will modify your contribution. This is a living document, and part of that is for all of us to let go of our egos.
• Sometimes other people may disagree with you. In such cases, defer to the experts and to the site admins.

Protocol

• The following protocol may not be changed without permission from the site admins.
• Admin team members may make changes without PRs, after discussing them with other admin members.
• Changes by other people, big and small, require a PR.

Relaxed Protocol

• Document editors who want to be able to edit specific contributions rapidly may put a notice at the top saying that the page is a work in progress together with their github name(s). Only they are allowed to modify that page any way that they want without discussion or a PR.
• All other edits to these pages require following the regular protocol.
• This status is temporary and may not be maintained for long periods of time.

Revoked Contribution Rights

• We love that you contribute to OCamlverse, but contributing to this resource is ultimately a privilege. We trust that you have the right intentions and knowledge to contribute. This privilege can be revoked.
• Failing to adhere to the required tone and attitude, the protocol, showing a lack of respect for the other contributors, or showing a serious lack of good judgement and receptivneness to comments, as determined by the managers of the site, can cause you to have your contributor rights revokes. You can still contribute via PR, but not directly merge content. And if we see improved behavior, you’ll get your contributor rights back.

Guidelines For Imported Content

Even though OCamlverse accepts links to content freely, ideally all content will be hosted on OCamlverse. The reason for this is that all content becomes outdated with time, and without permission to change it, we cannot adequately maintain documentation.

The process of importation starts with linking to the original source (with the author’s permission), crediting the author, and copying the content to OCamlverse. Over time, the content will then be gradually edited by OCamlverse contributors. Eventually, the original link may be completely irrelevant, at which point it may be removed.

Here are some good heuristics for choosing which content to import:

1. The content must be appropriately licensed so we can use it (or the owners give us permission.)
2. It is not sufficiently maintained where it is. If something is well maintained where it is, we shouldn’t be taking it in.
3. We should only import things we think we’re realistically able to maintain. OCamlverse will always have limited resources, and consideration must be made for our capabilities at any point in time, including the expertise of our contributors.