Edit Contributing ReadMe

[christinerose]

Since we're going to start actively encouraging contributions, I reviewed/revised the CONTRIBUTING.md doc.

I found these points confusing:

• the line: "This guide documents the best way to contribute to the project. If you're looking for a guide on how to setup the project and submit a contribution, you can refer to our HACKING guide." The first sentence says this guide is for contributing to the project, and the second sentence also says how to submit a contribution to the project via the HACKING guide. Are these two different project? Perhaps we can clarify this.
• the line: "To fix this content, you can edit those files directly and rebuild the website." Is "fix" the best word here? Perhaps "suggest a change or update" ? -- this reads as if they can change the site directly without opening a PR. Is that correct?
• this line: "Translating Content or Pages: for now we are focusing on getting OCaml.org ready for launch and will add more information about translation later." -- Since we've already launched OCaml.org, should this be updated or removed?
• If OMP is deprecated, should it just be removed from the list of Changelog examples?

[sabine]

Thank you @christinerose!

the line: "This guide documents the best way to contribute to the project. If you're looking for a guide on how to setup the project and submit a contribution, you can refer to our HACKING guide." The first sentence says this guide is for contributing to the project, and the second sentence also says how to submit a contribution to the project via the HACKING guide. Are these two different project? Perhaps we can clarify this.

CONTRIBUTING.md gives an overview of how to contribute and lists all the different ways one can contribute.

HACKING.md gives instructions on how to build and run the site locally - which is required for some contributions but not for all of them. Adding a job, for example, people can usually figure out how to do it without building and running the site locally. Making changes to the code, people definitely need the instructions in HACKING.md.

the line: "To fix this content, you can edit those files directly and rebuild the website." Is "fix" the best word here? Perhaps "suggest a change or update" ? -- this reads as if they can change the site directly without opening a PR. Is that correct?

yes, it's not always about fixing, so your wording of "suggest a change or update" is much better.
The GitHub UI allows them to edit, but when they try to save it opens a PR automatically because they are not maintainers on this repository.

this line: "Translating Content or Pages: for now we are focusing on getting OCaml.org ready for launch and will add more information about translation later." -- Since we've already launched OCaml.org, should this be updated or removed?

We are not doing translations in the near future as it would require significant code changes. People can use services like Google Translate for now. Indeed, we can either remove or tell people that we're just not doing it at this time.

If OMP is deprecated, should it just be removed from the list of Changelog examples?

@tmattio What is your opinion on this?

[christinerose]

Also @sabine: I see in data/news that there are three other directories: multicore, ocaml, and ocamlorg. In which would one submit a blog post? Should there be a directory for general blog posts, or would they go under ocamlorg. Right now only newsletters are in there.

[sabine]

For news, these are from "official" sources, and generally related to OCaml itself, the compiler and such.

We also have some blog posts under /data/planet/ocamlorg.

The whole OCaml Planet / Blog section is in need of tidying up.

[tmattio]

If OMP is deprecated, should it just be removed from the list of Changelog examples?

We can remove both ppxlib and omp, they are part of the Platform

[christinerose]

For news, these are from "official" sources, and generally related to OCaml itself, the compiler and such.

We also have some blog posts under /data/planet/ocamlorg.

The whole OCaml Planet / Blog section is in need of tidying up.

Ah! I'll make that clear in the revision. I put the SIGPLAN one in news/ocamlorg. Is that okay?

[christinerose]

We can remove both ppxlib and omp, they are part of the Platform

Done!

[christinerose]

For news, these are from "official" sources, and generally related to OCaml itself, the compiler and such.

We also have some blog posts under /data/planet/ocamlorg.

Done! (I think!)
Updated with /data/planet/ocamlorg along with an example post from in there. To clarify, these will still show up under "News" @sabine?

[christinerose]

@sabine, I think I made all the changes from your answers to my questions. Would you have another look to see if they're accurate, please?

[sabine]

Updated with /data/planet/ocamlorg along with an example post from in there. To clarify, these will still show up under "News" @sabine?

No, when you put a blog post under /data/planet/ocamlorg, then it shows up under "OCaml Community Blog", but it's an actual blog post hosted on ocaml.org (i.e. not a link to an external blog).

These posts will not show up under "News". Only the entries in /data/news show up on the "News" sidebar, which is reserved for official announcements.

ETA: This situation that we have two places to put ocamlorg blog posts is what I see in need of tidying up - we need to rework the community section and find clarity on how to proceed with the "News" - whether these should be a separate category of items (/data/news instead of /data/planet/official-news) in the first place.

[christinerose]

No, when you put a blog post under /data/planet/ocamlorg, then it shows up under "OCaml Community Blog", but it's an actual blog post hosted on ocaml.org (i.e. not a link to an external blog).

Oh! Okay! But it will go in the same section as the links to the external ones. Got it!

Fixed! Perhaps until it's all sorted, and only "official" news can be posted under news, which seems at the point to come from our team or Anil, we leave out that bit and just talk about the community blog for now? See if you like my changes, please.