Add a timezone guide for country/zone mappings

Author: gilmoreorless

docs/moment-timezone/01-using-timezones/08-getting-country-zones.md

@@ -6,6 +6,7 @@ signature: |
 ---
 
 To get a list of time zones for some country, use `moment.tz.zonesForCountry()`.
+This takes an [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) two-letter country code.
 
 ```js
 moment.tz.zonesForCountry('US');
@@ -17,13 +18,13 @@ By default this method returns zone names sorted alphabetically:
 ["America/Adak", "America/Anchorage", ... "Pacific/Honolulu"]
 ```
 
-To get also offsets, pass `true` as 2nd parameter:
+To also get offsets, pass `true` as the 2nd parameter:
 
 ```js
 moment.tz.zonesForCountry('CN', true);
 ```
 
-it returns array of objects with name and offset:
+In this case, it returns an array of objects with the zone's name and its offset for the **current date and time**.
 
 ```js
 [
@@ -32,6 +33,9 @@ it returns array of objects with name and offset:
 ]
 ```
 
-It's useful if you need to sort time zones by offset.
+It's useful if you need to sort time zones by offset, but be aware that the offsets can change throughout the year.
 
-All country codes can be retrieved using method `moment.tz.countries()`
+All known country codes in the data can be retrieved using method `moment.tz.countries()`.
+
+**Note:** Sometimes these methods might return unexpected data.
+See the [Countries and Zones guide](/timezone/guides/#/data-calculations/country-zones/) for more details.

guides/moment-timezone/01-data-calculations/02-limited-range.md

@@ -2,7 +2,7 @@
 title: Limited Data Ranges
 ---
 
-By default, Moment Timezone includes all the data from the [IANA Time Zone Database ("tzdb")](https://www.iana.org/time-zones).
+By default, Moment Timezone includes all the data from the IANA tzdb (see [Data Source](#/data-calculations/data-source/)).
 This covers past data as far back as the 1800s for some zones, and future data up to the year 2499.
 This is usually more data than required by most applications, so there are also some pre-built data bundles available with more limited year ranges.
 These are listed on the [project homepage](/timezone) and the ["Where to use it" documentation](/timezone/docs/#/use-it)

guides/moment-timezone/01-data-calculations/04-country-zones.md

@@ -0,0 +1,44 @@
+---
+title: Countries and Zones
+---
+
+Moment Timezone's [country-related APIs](/timezone/docs/#/using-timezones/getting-country-zones/) rely on known associations between zones and countries, which come directly from the IANA tzdb (see [Data Source](#/data-calculations/data-source/)).
+
+The mapping of zones to countries exposes a subtle nuance in the tzdb structure that doesn't match a lot of people's mental model of the data.
+This can sometimes catch out users who see something unexpected in the country data and assume it must be a bug.
+
+The key principle is that zone identifiers like `Europe/Berlin` and `Asia/Tokyo` are **labels** for regions of the world where the clocks have agreed since 1970.
+These regions are not specifically tied to a single country, and can span multiple countries if needed.
+This would be equally true if the labels didn't have city names at all, but instead were named something like `Europe/Zone073`.
+The city name is simply an aid to users to make the database more human-readable.
+
+The tzdb defines which countries use each time zone.
+But because the zones are named after cities, this can be easily misinterpreted to mean that a city is in multiple countries, which is incorrect.
+
+As an example, let's look at a line from the source [`zone1970.tab`](https://data.iana.org/time-zones/data/zone1970.tab):
+
+```
+CZ,SK	+5005+01426	Europe/Prague
+```
+
+This line is **not** indicating that the city of Prague is in both Czechia and Slovakia.
+It is saying that a time zone region—where clocks have agreed since 1970—can be used in both Czechia and Slovakia, and happens to have the _label_ of `Europe/Prague`.
+
+Moment Timezone also includes the backwards-compatibility data listed in the older (and deprecated) [`zone.tab`](https://data.iana.org/time-zones/data/zone.tab).
+This includes the line:
+
+```
+SK	+4809+01707	Europe/Bratislava
+```
+
+The `Europe/Bratislava` zone is an alias of `Europe/Prague`, so there's no difference in the processed time zone data.
+
+All this means that the results from Moment Timezone's country APIs can give some seemingly-unintuitive results that are correct according to the data model:
+
+```js
+moment.tz.zonesForCountry('CZ'); // ["Europe/Prague"]
+moment.tz.zonesForCountry('SK'); // ["Europe/Bratislava", "Europe/Prague"]
+
+moment.tz.zone('Europe/Bratislava').countries(); // ["SK"]
+moment.tz.zone('Europe/Prague').countries();     // ["CZ", "SK"]
+```