v3.ocaml.org-rescript
v3.ocaml.org-rescript copied to clipboard
ocaml
Documentation - CONTRIBUTING.md - Improvement.
Hello, I believe the sections under the Contributing.md document can be improved.
Here are a few suggestions -
- Linking - While reading, a person may want to jump directly to the repository and sites that have been mentioned but would have to browse which may get a little annoying.
- Reducing the use of Passive voice and Indirect speech - The vast majority of sentences in technical writing are usually in active voice and direct speech.
For example:
This:
If you are unsure if your change will be accepted or if want to discuss the approach before diving in, please create an issue and pose questions
Can be said as:
If you are not sure whether your changes will be accepted or want to discuss the method before delving into it, please create an issue and ask it.
Not a lot of differences but clearer sentences can lead to better communication.
- Just a little neatening up of the document such as capitalization here and there.
PS: I) I realize that this is not a lot but I believe can be helpful. 2) The Code of Conduct section and Architecture section - I don't know if these sections have been touched upon, as I am very new here, but if not I would like to help with it.
Would it be okay if I work on this @rdavison, @tmattio, and @patricoferris? I would be really glad to hear more inputs, requirements, and/or suggestions.
Hi @chicken-biryani! Thanks a lot for the suggestions. I agree that improving the contributing guide would be very valuable, so any contribution would be more than welcome 🙂
Hey @tmattio, here's a rough outline for the Contributing.md. .
If there are any additions, modifications, requirements, and/or deletions please do let me know.
PS: This is just the outline. I will make the wording more clear as and when I set it up myself.
@chicken-biryani This looks really good, thanks 🙂
We have merged all the repositories under a single umbrella in the v3.ocaml.org-server repository. Would you mind opening a PR with the updated contributing guide there?
Hey @tmattio I am a little confused- to my knowledge I don't think it's possible to make PR from one repository to another. If that is possible and is what is supposed to be done then please let me know, through a document or something that could help me?
Or do I have to make changes is v3.ocaml.org-server's Contributing.md?
Apologies. I have never made PRs across repositories so it;s a little comfusing.
Or do I have to make changes is v3.ocaml.org-server's Contributing.md?
Exactly, a single PR should be made on v3.ocaml.org-server, which updates the contributing guide there: https://github.com/ocaml/v3.ocaml.org-server/blob/main/CONTRIBUTING.md