First shot at contributing rules

[DavidBruant]

This is a first draft
All feedback is welcome

My intention is to have something short quickly approved and that we can iterate from here over time

[erights]

I notice that some of our own documentation is *.rst rather than *.md . Should we suggest that contributions can/should be *.rst ? How do we decide when to use which?

Attn @katelynsills @Chris-Hibbert @tatyana0219 @btulloh

[DavidBruant]

for reference, i don't have a strong intention on markdown, it's only a first proposition

I notice that some of our own documentation is *.rst

i hadn't noticed that, thanks for the info

The points i find positive about markdown are:

• Easy to get started when you already know how to write with Microsoft Word (!), because text is valid markdown and paragraph are naturally understood
  • simple learning curve (heading levels, bold, underline, links)
• Fairly popular (github/~Trello/~Slack), so lots of people are probably already familiar + there are lots of markdown-related resources on the web
• Web-friendliness: there is a natural transformation from markdown to HTML (and it takes only minutes to transform a github repo with markdown files into a website)
• complex layouts and styling are possible because HTML can be written inside markdown + it's easy to add CSS/JavaScript to a resource in markdown

From what i've understood, one downside of markdown is that it can be harder to work with when trying to write a book, but i don't have this experience myself, so i cannot expand on that

[Chris-Hibbert]

MarkDown is certainly a reasonable place to start. Let's agree that that's what we're using for most purposes.

If we need to use something else for some purposes, or eventually change to a different standard, we'll deal with that then.

[DavidBruant]

I created a follow-up issue on the *.rst files: #19

[DavidBruant]

I'll wait for @erights to come back from TC39 and if there is no urgent reason not to merge this PR, i'll merge it
And everything can be modified afterwards; a github repo is de facto a wiki

[katelynsills]

Closing as outdated