diff options
| -rw-r--r-- | CONTRIBUTING.markdown | 70 | ||||
| -rw-r--r-- | README.markdown | 101 |
2 files changed, 99 insertions, 72 deletions
diff --git a/CONTRIBUTING.markdown b/CONTRIBUTING.markdown new file mode 100644 index 00000000..9ee33ebc --- /dev/null +++ b/CONTRIBUTING.markdown @@ -0,0 +1,70 @@ +# 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. + +**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. + +## Style Guidelines + +- **Keep lines of under 80 chars** + + Try to keep **line length in code blocks to 80 characters or fewer**. + + Otherwise, the text will overflow and look odd. +- **Prefer example to exposition** + + 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. + + 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) + + +### 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 that +some key information be defined in the header. + +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. + +Here's an example header for an Esperanto translation of Ruby: + +```yaml +--- +language: ruby +filename: learnruby-epo.ruby +contributors: + - ["Doktor Esperanto", "http://example.com/"] + - ["Someone else", "http://someoneelseswebsite.com/"] +lang: ep-ep +--- +``` diff --git a/README.markdown b/README.markdown index 092785f8..a71e85bd 100644 --- a/README.markdown +++ b/README.markdown @@ -1,88 +1,45 @@ -# [Learn X in Y minutes](http://learnxinyminutes.com) +# [Learn X in Y minutes][1] Whirlwind tours of (several, hopefully many someday) popular and -ought-to-be-more-popular programming languages, presented as valid, -commented code and explained as they go. +ought-to-be-more-popular programming languages, presented as valid, commented +code and explained as they go. ## We need YOU!... -... to write more inline code tutorials. Just grab an existing file from -this repo and copy the formatting (don't worry, it's all very simple). -Make a new file, send a pull request, and if it passes muster I'll get it up pronto. -Remember to fill in the "contributors" fields so you get credited -properly! +... to write more inline code tutorials. Just grab an existing file from this +repo and copy the formatting (don't worry, it's all very simple). Make a new +file, send a pull request, and if it passes muster I'll get it up pronto. +Remember to fill in the "contributors" fields so you get credited properly! ## 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 tag your issues and pull requests with [language/lang-code] at the beginning** -**(e.g. [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 +For a detailed style guide, please review the full [CONTRIBUTING][2] guidelines. -* **Keep lines under 80 chars** -* **Prefer example to exposition** -* **Eschew surplusage** -* **Use UTF-8** - -Long version: - -* Try to keep **line length in code blocks to 80 characters or fewer**, or they'll overflow - and look odd. - -* Try to use as few words as possible. Code examples are preferred over exposition in all cases. - -* We welcome newcomers, but the target audience for this site is programmers with some experience. - So, try to avoid explaining basic concepts except for those specific to the language in question, - to keep articles succinct and scannable. We all know how to use Google here. - -* For translations (or English articles with non-ASCII characters), please make sure your file is - UTF-8 encoded, and 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 that some key information be defined in the header. - -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. - -Here's an example header for an Esperanto translation of Ruby: +## License -```yaml ---- -language: ruby -filename: learnruby-epo.ruby -contributors: - - ["Doktor Esperanto", "http://example.com/"] - - ["Someone else", "http://someoneelseswebsite.com/"] -lang: ep-ep ---- -``` +Contributors retain copyright to their work, and can request removal at any +time. By uploading a doc here, you agree to publish your work under the default +[Creative Commons Attribution-ShareAlike 3.0 Unported][3] licensing included on +each doc page. -## License +Anything not covered by the above -- basically, this README -- you can use as +you wish, I guess. -Contributors retain copyright to their work, and can request removal at any time. -By uploading a doc here, you agree to publish your work under the default -[Creative Commons Attribution-ShareAlike 3.0 Unported](http://creativecommons.org/licenses/by-sa/3.0/deed.en_US) -licensing included on each doc page. -Anything not covered by the above -- basically, this README -- you can use -as you wish, I guess. +[1]: http://learnxinyminutes.com +[2]: /CONTRIBUTING.markdown +[3]: http://creativecommons.org/licenses/by-sa/3.0/deed.en_US |