diff options
Diffstat (limited to 'CONTRIBUTING.markdown')
| -rw-r--r-- | CONTRIBUTING.markdown | 56 |
1 files changed, 34 insertions, 22 deletions
diff --git a/CONTRIBUTING.markdown b/CONTRIBUTING.markdown index d7468898..9ee33ebc 100644 --- a/CONTRIBUTING.markdown +++ b/CONTRIBUTING.markdown @@ -1,16 +1,18 @@ # Contributing -All contributions are welcome, from the tiniest typo to a brand new article. Translations -in all languages are welcome (or, for that matter, original articles in any language). -Send a pull request or open an issue any time of day or night. +All contributions are welcome, from the tiniest typo to a brand new article. +Translations in all languages are welcome (or, for that matter, original +articles in any language). Send a pull request or open an issue any time of day +or night. -**Please prepend the tag `[language/lang-code]` to your issues and pull requests.** For example, -`[python/en]` for English Python. This will help everyone pick out things they care about. +**Please prepend the tag `[language/lang-code]` to your issues and pull +requests.** For example, `[python/en]` for English Python. This will help +everyone pick out things they care about. -We're happy for any contribution in any form, but if you're making more than one major change -(i.e. translations for two different languages) it would be super cool of you to make a -separate pull request for each one so that someone can review them more effectively and/or -individually. +We're happy for any contribution in any form, but if you're making more than one +major change (i.e. translations for two different languages) it would be super +cool of you to make a separate pull request for each one so that someone can +review them more effectively and/or individually. ## Style Guidelines @@ -21,28 +23,38 @@ individually. + Try to use as few words as possible. + Code examples are preferred over exposition in all cases. - **Eschew surplusage** - + We welcome newcomers, but the target audience for this site is programmers with some experience. - + Try to avoid explaining basic concepts except for those specific to the language in question. + + We welcome newcomers, but the target audience for this site is programmers + with some experience. + + Try to avoid explaining basic concepts except for those specific to the + language in question. + Keep articles succinct and scannable. We all know how to use Google here. - **Use UTF-8** - + For translations (or EN articles with non-ASCII characters) please make sure your file is UTF-8 encoded. - + Try to leave out the byte-order-mark at the start of the file. (`:set nobomb` in Vim) + + For translations (or EN articles with non-ASCII characters) please make sure + your file is UTF-8 encoded. + + Try to leave out the byte-order-mark at the start of the file. (`:set nobomb` + in Vim) -## Header configuration -The actual site uses Middleman to generate HTML files from these Markdown ones. Middleman, or at least -the custom scripts underpinning the site, requires key information to be defined in the header. +### Header configuration -The following fields are necessary for English articles about programming languages: +The actual site uses Middleman to generate HTML files from these Markdown ones. +Middleman, or at least the custom scripts underpinning the site, requires that +some key information be defined in the header. -- **language** - The *programming language* in question -- **contributors** - A list of [author, URL] arrays to provide credit +The following fields are necessary for English articles about programming +languages: + +- **language** The *programming language* in question +- **contributors** A list of [author, URL] lists to credit Other fields: -- **filename** - The filename for this article's code. It will be fetched, mashed together, and made downloadable. - + For non-English articles, *filename* should have a language-specific suffix. -- **lang** - For translations, the human language this article is in. For categorization, mostly. +- **filename**: The filename for this article's code. It will be fetched, mashed + together, and made downloadable. + + For non-English articles, *filename* should have a language-specific + suffix. +- **lang**: For translations, the human language this article is in. For + categorization, mostly. Here's an example header for an Esperanto translation of Ruby: |