Tweaks to wording in the Guide

Author: stasm

guide/builtins.md

@@ -8,13 +8,6 @@ last-notice =
     Last checked: { DATETIME($lastChecked, day: "numeric", month: "long") }.
 ```
 
-```json
-{
-    "lastChecked": "2016-04-22T08:13:56.354Z",
-    "unreadEmails": 5
-}
-```
-
 In most cases, Fluent will automatically select the right formatter for the
 argument and format it into a given locale.
 

guide/external.md

@@ -22,7 +22,3 @@ unreadEmails = { $user } has { $emailCount } unread emails.
 There are all kinds of external data that might be useful in providing a good
 localization: user names, number of unread messages, battery level, current
 time, time left before an alarm goes off, etc.
-
-To reference a variable, use the dollar syntax in your FTL code:
-`$user`. `user` has to be defined in the context data. In the examples below,
-we insert the value of a context data variable into a message's value.

guide/selectors.md

@@ -1,32 +1,29 @@
 # Selectors
 
 ```
-emails = { $unreadEmails ->
+emails =
+    { $unreadEmails ->
         [one] You have one unread email.
        *[other] You have { $unreadEmails } unread emails.
     }
 ```
 
-```json
-{
-    "unreadEmails": 5
-}
-```
-
 One of the most common cases when a localizer needs to use a placeable is when
 there are multiple variants of the string that depend on some external
-argument. FTL provides the select expression syntax, which chooses one of the
-provided variants based on the given selector.
+argument. In the example above, the `emails` message depends on the value of
+the `$unreadEmails` external argument.
 
-The `*` indicator identifies the default selection. A default selection is required.
+FTL has the select expression syntax which allows to define multiple variants
+of the translation and choose between them based on the value of the
+selector. The `*` indicator identifies the default variant. A default
+variant is required.
 
-The selector may be a string, in which case it will be compared directly to the
-keys of variants defined in the select expression. For number selectors, the
-variant keys either match the number exactly or they match the [CLDR plural
-category](http://www.unicode.org/cldr/charts/30/supplemental/language_plural_rules.html)
-for the number. The possible categories are: `zero`, `one`, `two`, `few`,
-`many`, and `other`. For instance, English has two plural categories: `one` and
-`other`.
+The selector may be a string, in which case it will be compared directly to
+the keys of variants defined in the select expression. For selectors which
+are numbers, the variant keys either match the number exactly or they match
+the [CLDR plural category][] for the number. The possible categories are:
+`zero`, `one`, `two`, `few`, `many`, and `other`. For instance, English has
+two plural categories: `one` and `other`.
 
 If the translation requires a number to be formatted in a particular
 non-default manner, the selector should use the same formatting options. The
@@ -35,8 +32,11 @@ which, for some languages, might be different than the category of the
 unformatted number:
 
 ```
-your-score = { NUMBER($score, minimumFractionDigits: 1) ->
+your-score =
+    { NUMBER($score, minimumFractionDigits: 1) ->
         [0.0]   You scored zero points. What happened?
        *[other] You scored { NUMBER($score, minimumFractionDigits: 1) } points.
     }
 ```
+
+[CLDR plural category]: http://www.unicode.org/cldr/charts/30/supplemental/language_plural_rules.html

guide/variants.md

@@ -18,12 +18,14 @@ As we stated at the beginning of this guide, messages primarily consist of
 string values. A single string value can have multiple branches, or variants,
 which are chosen based on the value of a selector. In some cases, however, we
 don't need any selector and instead just want to define multiple variants of
-the message and use them from within other messages. For instance, in languages
-that use noun declension, `-brand-name` may need to be declined when referred to
+the message and use them from within other messages.
+
+This is most useful for [terms](terms.html). For instance, in languages that
+use noun declension, `-brand-name` may need to be declined when referred to
 from other messages.
 
 FTL lets you define variants without a selector. Think of them as facets of the
-same message. You can refer to them using the `message[variant key]` syntax.
+same message. You can refer to them using the `identifier[variant key]` syntax.
 
 For instance, in many inflected languages (e.g. German, Finnish, Hungarian, all
 Slavic languages), the *about* preposition governs the grammatical case of the