From 5a87423e209ee77b53e20f70ccc87c26511c4869 Mon Sep 17 00:00:00 2001
From: Adam Bard <github@adambard.com>
Date: Thu, 5 Sep 2013 10:52:17 -0700
Subject: [PATCH] Update README.markdown

---
 README.markdown | 33 +++++++++++++++++++++++++++++----
 1 file changed, 29 insertions(+), 4 deletions(-)

diff --git a/README.markdown b/README.markdown
index fe72df6c..dc379a9b 100644
--- a/README.markdown
+++ b/README.markdown
@@ -12,12 +12,24 @@ Make a new file, send a pull request, and if it passes muster I'll get it up pro
 Remember to fill in the "contributors" fields so you get credited
 properly!
 
-### Contributing
+## Contributing
 
 All contributions 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.
 
-#### Style Guidelines
+**Please tag your issues 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.
+
+### Style 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.
@@ -29,9 +41,9 @@ in all languages are welcome (or, for that matter, original articles in any lang
   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.
+  utf-8 encoded, and try to leave out the byte-order-mark at the start of the file. (`:set nobomb` in vim)
 
-#### Header configuration
+### 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, required that some key information be defined in the header.
@@ -47,6 +59,19 @@ Other fields:
   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
+---
+```
+
 ## License
 
 Contributors retain copyright to their work, and can request removal at any time.