[RFC] Contribution Guidelines

[HugoGranstrom]

I think it might be good to write up some short contribution guidelines for the future when people (hopefully) will be contributing some articles. Things that might be worth discussing and writing some guidelines for:

• Language/Spelling/Grammar: How strict should we be? Should we (the maintainers) proof-read every submission and note every single error or should we just say "Fix the grammatical errors please" and let them figure out themself?
• Code style: I guess we will just have them format it using nimpretty (with longer lines than the default?). Or we add it as part of the deployment automatically / as a commit hook.
• New Topics: How strict should we be about introducing new topics (out of the ordinary) that may be rather niched as to not pollute the top-level of the TOC?

Any thoughts on this?

[zetashift]

For code style I think https://status-im.github.io/nim-style-guide/ is still the best and clear style out there. I'm also okay with just following NEP-1 and nimpretty formatting(lineLen = 120 too).

Concerning "Language/Spelling/Grammar", spelling should be correct and strict. But grammar and language can be more fluid and can be discussed on a proof-reading pass. I'd like to see discussions "I'd like to see this written in Y form" or "This sentence comes over a certain X way". Things like https://github.com/errata-ai/vale can help with this.

And lastly "New Topics", as long as they exemplify the "getting-started" scope and goals, I'd say it's all good. If it's very elaborate or too short, it should be discussed if it's better off in it's own Nimibook or maybe posted on the Nim blog.

[HugoGranstrom]

For code style I think status-im.github.io/nim-style-guide is still the best and clear style out there. I'm also okay with just following NEP-1 and nimpretty formatting(lineLen = 120 too).

Yes that style guide is really good. If it only had a nimpretty alternative to enforce it. That's the main reason for picking nimpretty in my eyes as we don't have to bother with checking the style of the code.

Concerning "Language/Spelling/Grammar", spelling should be correct and strict. But grammar and language can be more fluid and can be discussed on a proof-reading pass. I'd like to see discussions "I'd like to see this written in Y form" or "This sentence comes over a certain X way". Things like errata-ai/vale can help with this.

Had never heard of vale before but it seems very interesting. I'm with you on the strict spelling but more free grammar and language. The only time we should remark it is if it's making it harder to understand the text. So idk if something like vale would be of much use for us?

And lastly "New Topics", as long as they exemplify the "getting-started" scope and goals, I'd say it's all good. If it's very elaborate or too short, it should be discussed if it's better off in it's own Nimibook or maybe posted on the Nim blog.

I was more thinking about putting niche topics in a misc section or something like that if the don't fit anywhere else. :) Elaborate things can get their own subtopics imo.

[zetashift]

Yes that style guide is really good. If it only had a nimpretty alternative to enforce it. That's the main reason for picking nimpretty in my eyes as we don't have to bother with checking the style of the code.

Could maybe use https://github.com/FedericoCeratto/nimfmt for that.

Had never heard of vale before but it seems very interesting. I'm with you on the strict spelling but more free grammar and language. The only time we should remark it is if it's making it harder to understand the text. So idk if something like vale would be of much use for us?

I originally recommended Vale because it's just an helpful tool writing prose, I don't want to enforce anything to the writers haha, but say somebody would want to write something but isn't sure if "their language is correct" then Vale can be a boon, like just pick a style from here https://github.com/errata-ai/styles#available-styles and go wild! But yes if it gets too difficult then remarks can be made, but this is in a proof-read phase, Vale comes in handy in the writing phase.

I was more thinking about putting niche topics in a misc section or something like that if the don't fit anywhere else. :) Elaborate things can get their own subtopics imo.

Ah yes, fair enough, I like this too :D.

[HugoGranstrom]

Could maybe use FedericoCeratto/nimfmt for that.

It looks promising but it seems like it's unmaintained and a lot of the boxes in the readme aren't ticked 🤔

I originally recommended Vale because it's just an helpful tool writing prose, I don't want to enforce anything to the writers haha, but say somebody would want to write something but isn't sure if "their language is correct" then Vale can be a boon, like just pick a style from here errata-ai/styles#available-styles and go wild! But yes if it gets too difficult then remarks can be made, but this is in a proof-read phase, Vale comes in handy in the writing phase.

Oh okay, I misunderstood the purpose of Vale then :) If it can help people write better during the writing phase it's brilliant! It could be a great way to get more people to write, especially the ones who are insecure about their English. Just point them to something like this and they might consider writing after all.

Ah yes, fair enough, I like this too :D.

Nice! :D

[HugoGranstrom]

@zetashift While reviewing Vindaar's post on curve-fitting I noticed some odd code formatting that wasn't present in the original code. Then it hit me that Nimib let's the compiler handle the code before rendering it so there is already a kind of code formatting that we can't change whatever code-formatter we use.