Drafts keep their subscribers when an update doesn't address them

sections/cloud_files.md

@@ -242,8 +242,11 @@ Update a cloud file
 
 Update accepts `title`, `url`, `service`, and `description`, and all four are sent
 on every update — the controller replaces the recordable on each call rather than
-patching individual fields. Updating a drafted cloud file also publishes it,
-applying any `subscriptions` sent with the request.
+patching individual fields. Updating a drafted cloud file also publishes it.
+
+Subscribers are only replaced when you address them: omit both `subscriptions` and
+`notify` and a drafted cloud file keeps its current subscribers; send either one to
+recompute the list. The creator is always on the list.
 
 ###### Example JSON Request
 <!-- START PUT PAYLOAD /buckets/1/cloud_files/2.json -->

sections/documents.md

@@ -231,7 +231,9 @@ Publish a [draft](drafts.md) document by updating it with `status` set to `activ
 }
 ```
 
-A status-only update fails with `400 Bad Request` (the `document` parameters are required), and omitting a field clears its value. Publishing posts the document and notifies its subscribers exactly once — the same publication side-effects as [publishing a message](messages.md#publishing-a-draft).
+A status-only update fails with `400 Bad Request` (the `document` parameters are required), and omitting a field clears its value.
+
+Subscribers are the exception. They're only replaced when you address them: omit both `subscriptions` and `notify` and a drafted document keeps its current subscribers; send either one to recompute the list. The creator and whoever makes the update are always on the list. Publishing posts the document and notifies its subscribers exactly once — the same publication side-effects as [publishing a message](messages.md#publishing-a-draft).
 
 
 Legacy project-scoped routes

sections/google_documents.md

@@ -225,8 +225,11 @@ Update a Google document
 
 Update accepts `title`, `url`, `document_type`, and `description`, and all four are
 sent on every update — the controller replaces the recordable on each call rather than
-patching individual fields. `status` is also accepted; updating a drafted document
-applies any `subscriptions` sent with the request.
+patching individual fields. `status` is also accepted.
+
+Subscribers are only replaced when you address them: omit both `subscriptions` and
+`notify` and a drafted Google document keeps its current subscribers; send either one
+to recompute the list. The creator is always on the list.
 
 ###### Example JSON Request
 <!-- START PUT PAYLOAD /buckets/1/google_documents/2.json -->

sections/messages.md

@@ -454,6 +454,8 @@ Update a message
 
 This endpoint will return `200 OK` with the current JSON representation of the message if the update was a success. See the [Get a message](#get-a-message) endpoint for more info on the payload.
 
+Subscribers are only replaced when you address them: omit both `subscriptions` and `notify` and a drafted message keeps its current subscribers; send either one to recompute the list. The creator and whoever makes the update are always on the list. Note that this differs from [creating a message](#create-a-message), where omitting `subscriptions` subscribes everyone on the project.
+
 ###### Example JSON Request
 
 ```json
@@ -480,7 +482,7 @@ Publish a [draft](drafts.md) message by updating it with `status` set to `active
 { "status": "active" }
 ```
 
-A message update **merges** the fields you send, so you don't need to resend `subject` or `content` — the draft's existing content is preserved.
+A message update **merges** the fields you send, so you don't need to resend `subject` or `content` — the draft's existing content is preserved. The draft's subscribers are preserved too, so publishing notifies the people already on the list unless you send `subscriptions` or `notify` to change it.
 
 Publishing is what actually posts the message, and it happens exactly once: each subscriber who should hear about it receives a single notification (delivered shortly after, once notifications are dispatched). Creating or re-saving a draft notifies no one — only publishing does. (Documents publish the same way; see [Publishing a draft](documents.md#publishing-a-draft) in the documents section.)
 

sections/schedule_entries.md

@@ -331,6 +331,8 @@ This endpoint will return `200 OK` with the current JSON representation of the s
 
 Participants are only replaced when you address them: omit `participant_ids` and the entry keeps its current participants; send `"participant_ids": []` to remove them all.
 
+Subscribers work the same way, except that participants address them too — a drafted entry's subscribers are derived from its participants. So a draft keeps its current subscribers only when the request omits `subscriptions`, `notify`, **and** the participant parameters; sending any of them recomputes the list, which is what unsubscribes someone you drop from the entry. The creator is always on the list.
+
 ###### Example JSON Request
 
 ```json