-
Notifications
You must be signed in to change notification settings - Fork 40
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
First shot at contributing rules #11
Conversation
|
||
Here are a couple of rules to follow: | ||
- The content must be written in **English** | ||
- The content must be written in **markdown** (`.md` file extension) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I created a follow-up issue on the *.rst files: #19
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
Closing as outdated |
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