Update documentation around calendars

- this was missed when the last set of calendar changes
  were made.

docs/calendars.md

@@ -1,32 +1,42 @@
 # Calendars
 
-Calendar JSON data files are stored in `lib/data/<type>.json`, with a `divisions` hash for separate data per region (`united-kingdom`, `england-and-wales`, `scotland` or `northern-ireland`).
+## Bank Holidays
+
+The calendar data is in `lib/data/bank-holidays.json`, with a `divisions` hash for separate data per region (`united-kingdom`, `england-and-wales`, `scotland` or `northern-ireland`).
 
 Each type's data file contains a list of divisions, containing a list of years, each with a list of events:
 
 ```json
 {
-  "title": "UK bank holidays",
-  "description": "UK bank holidays calendar - see UK bank holidays and public holidays for 2012 and 2013",
+  "title": "bank_holidays.calendar.title",
+  "description": "bank_holidays.calendar.description",
   "divisions": {
     "england-and-wales": {
-      "title": "England and Wales",
+      "title": "common.nations.england-and-wales_slug",
       "2011": [{
-        "title": "New Year's Day",
+        "title": "bank_holidays.new_year",
         "date": "02/01/2011",
-        "notes": "Substitute day"
+        "notes": ""
       }]
     }
   }
 }
 ```
 
-The division `title` attribute is optional.  If this is not present the slug will be humanized and used instead.
+The strings are all localisation paths, which allows the calendar to be available in English at /bank-holidays and
+in Welsh at /gwyliau-banc
+
+## When do the clocks change
+
+The calendar data is in `lib/data/when-do-the-clocks-change.json`. Since the clocks change in all four regions at
+the same time, there is only one common division. As with the bank holiday data, all strings are localisation paths (although at the moment this data exists only for english)
 
 ## Publishing Calendars
 
-You'll need to run the `publishing_api:publish_calendars` rake task against the `frontend` app on the `frontend` machine.
+These two calendars are special routes, published using
+
+`rails special_routes:publish`
 
-This will update <https://www.gov.uk/when-do-the-clocks-change> and <https://www.gov.uk/bank-holidays>.
+in `publishing-api`.
 
-To test locally, you may need to `govuk-docker-up` on `publishing-api` in a separate shell, before you run the rake task. You may also need to run the rake task a couple of times if you encounter timeouts.
+Note that the routes do not need to be republished when data in the json file is changed - only if the routes are missing from content-store, or if the rendering app changes.