Merge pull request #1753 from onebree/contrib

Add contributing-specific file

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