create general guidelines readme (#325)

* create general guides readme

* Update ID translation instructions.

1 files changed, 73 insertions, 0 deletions

diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000000..baad7bb905
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,73 @@
+# General guidelines for MDN translated content
+
+In this README you can find a collection of general guidelines for translating
+MDN content, which apply to every locale.
+
+For guidelines relating to specific locales, we have locale-specific docs in
+subdirectories:
+
+- [Russian translation guide / Участие в переводе](ru/translation-guide.md)
+
+If you want to add a guide to document some specific guidelines for your locale
+and it does not already appear here, you are welcome to add one, or
+[talk to the locale teams](https://github.com/mdn/translated-content/blob/docs-readme/README.md)
+about it. Similarly, if you can think of a good general guideline that you'd
+like to add here, feel free to create an issue to talk about it.
+
+## Translating heading IDs
+
+Our article headings are nearly always given IDs, so that we can automatically
+generate in-article navigation, identify code blocks to create live samples,
+and other reasons too. When translating headings, you don't need to translate
+the ID too; the rest of the slug is not translated, so this keeps it all
+consistent.
+
+For example:
+
+```html
+<h2 id="tutorials">Tutorials</h2>
+```
+
+in the `fr` locale would be
+
+```html
+<h2 id="tutorials">Tutoriels</h2>
+```
+
+We generally advise that you write all IDs in lower-case. The platform
+automatically converts them at render time anyway, but keeping them lower-case
+means that there is less chance of a manually-created anchor link not working
+because of the conversion.
+
+## Translating code blocks
+
+When translating code blocks, it is fine to translate comments, strings,
+variable names, and output representations.
+
+However, don't translate actual code terms such as syntax. The example needs
+to still work after you are finished with it.
+
+Also, when considering translating examples, bear in mind that some examples
+will link to a live version or source code on a separate repo. You might also
+want to consider creating a translated version of the external code examples
+to link to from your translated page.
+
+## Line breaks in HTML source
+
+In some of the article source code, you may find line breaks in the block-level
+elements that aren't strictly necessary, for example:
+
+```html
+<p>The
+  <code><strong>HTMLCanvasElement</strong></code><strong><code>.transferControlToOffscreen()</code></strong>
+  method transfers control to an {{domxref("OffscreenCanvas")}} object, either on the main
+  thread or on a worker.</p>
+
+<pre
+  class="brush: js">OffscreenCanvas HTMLCanvasElement.transferControlToOffscreen()</pre>
+```
+
+Generally we don't use line breaks like this in our source code, so you are
+free to remove them if you want to, and don't add them in when creating new
+translations. However, don't spend too much time trying to remove these, as
+they don't make any difference to the final rendered result.