docs: Improve Mobile push notification service documentation.

docs/production/mobile-push-notifications.md

@@ -1,94 +1,71 @@
 # Mobile push notification service
 
-Zulip's iOS and Android mobile apps support receiving push
+Zulip's iOS and Android [mobile apps](https://zulip.com/apps/) support receiving
-notifications from Zulip servers to let users know when new messages
+push notifications from Zulip servers to let users know when new messages have
-have arrived. This is an important feature to having a great
+arrived. This is an important feature for having a great mobile app experience.
-experience using the Zulip mobile apps.
 
-For technical reasons (explained below), in order to deliver mobile
+To set up mobile push notifications, you will need to register your Zulip server
-push notifications in the app store versions of our mobile apps, you
+with the Zulip mobile push notification service. This service will forward push
-will need to register your Zulip server with the Zulip mobile push
+notifications generated by your server to users' mobile apps.
-notification service. This service will forward push notifications
-generated by your server to the Zulip mobile app automatically.
 
 ## How to sign up
 
-Starting with Zulip 1.6 for both Android and iOS, Zulip servers
+You can enable the mobile push notification service for your Zulip server as
-support forwarding push notifications to a central push notification
+follows:
-forwarding service. Accessing this service requires outgoing HTTPS
-access to the public Internet; if that is restricted by a proxy, you
-will need to [configure Zulip to use your outgoing HTTP
-proxy](deployment.md#customizing-the-outgoing-http-proxy)
-first.
 
-You can enable this for your Zulip server as follows:
+1. Make sure your server has outgoing HTTPS access to the public Internet. If
+   that is restricted by a proxy, you will need to [configure Zulip to use your
+   outgoing HTTP proxy](deployment.md#customizing-the-outgoing-http-proxy)
+   first.
+
+1. Decide whether to upload basic usage statistics. Systems using the Mobile
+   Push Notifications Service will, by default, submit basic usage statistics
+   (e.g. Zulip version, number of users, number of messages sent) to the service.
+   These statistics help Zulip's maintainers understand how many people are
+   self-hosting Zulip in order to allocate resources towards supporting
+   self-hosted installations.
+
+   Our use of these statistics is governed by the same [Terms of
+   Service](https://zulip.com/policies/terms) and [Privacy
+   Policy](https://zulip.com/policies/privacy) that covers the Mobile Push
+   Notifications Service itself. If your organization does not want to submit these
+   statistics, you can disable this feature during setup or at any time by setting
+   `SUBMIT_USAGE_STATISTICS=False` in `/etc/zulip/settings.py`.
 
 1. Uncomment the
    `PUSH_NOTIFICATION_BOUNCER_URL = 'https://push.zulipchat.com'` line
-   in your `/etc/zulip/settings.py` file (i.e. remove the `#` at the
+   in your `/etc/zulip/settings.py` file (i.e., remove the `#` at the
    start of the line), and [restart your Zulip
-   server](settings.md#making-changes). If you
+   server](settings.md#making-changes).
-   installed your Zulip server with a version older than 1.6, you'll
-   need to add the line (it won't be there to uncomment).
 
-1. If you're running Zulip 1.8.1 or newer, you can run the
+1. Run the registration command. If you installed Zulip directly on the server
-   registration command:
+   (without Docker), run as root:
 
-   ```bash
+   ```
-   # As root:
    su zulip -c '/home/zulip/deployments/current/manage.py register_server'
-   # Or as the zulip user, you can skip the `su zulip -c`:
+   ```
-   /home/zulip/deployments/current/manage.py register_server
 
-   # docker-zulip users can run this inside the container with `docker exec`:
+   Or if you're using Docker, run:
+
+   ```
    docker exec -it -u zulip <container_name> /home/zulip/deployments/current/manage.py register_server
    ```
 
-   This command will print the registration data it would send to the
+   This command will print the registration data it would send to the mobile
-   mobile push notifications service, ask you to accept the terms of
+   push notifications service, ask you to accept the terms of service, and if
-   service, and if you accept, register your server. If you have trouble,
+   you accept, register your server. If you have trouble, [contact Zulip
-   email support@zulip.com with the output of this command.
+   support](https://zulip.com/help/contact-support) with the output of this
+   command.
 
-1. If you or your users have already set up the Zulip mobile app,
+1. If you or your users have already set up the Zulip mobile app, you'll each
-   you'll each need to log out and log back in again in order to start
+   need to log out of the mobile app, and log back in again in order to start
    getting push notifications.
 
-Congratulations! You've successfully set up the service.
+Congratulations! You've successfully set up the service. You can now test mobile
+push notifications by following [these
+instructions](https://zulip.com/help/mobile-notifications#testing-mobile-notifications).
 
-If you'd like to verify that everything is working, you can do the
+## Why a push notification service is necessary
-following. Please follow the instructions carefully:
-
-- [Configure mobile push notifications to always be sent][mobile-notifications-always]
-  (normally they're only sent if you're idle, which isn't ideal for
-  this sort of testing).
-- On an Android device, download and log in to the
-  [Zulip Android app](https://play.google.com/store/apps/details?id=com.zulipmobile).
-  If you were already logged in before configuring the server, you'll
-  need to log out first, since the app only registers for push
-  notifications on login.
-- Hit the home button, so Zulip is running in the background, and then
-  have **another user** send you a **direct message** (By default,
-  Zulip only sends push notifications for direct messages sent by other
-  users and messages mentioning you). A push notification should appear
-  in the Android notification area.
-
-[mobile-notifications-always]: https://zulip.com/help/test-mobile-notifications
-
-## Updating your server's registration
-
-Your server's registration includes the server's hostname and contact
-email address (from `EXTERNAL_HOST` and `ZULIP_ADMINISTRATOR` in
-`/etc/zulip/settings.py`, aka the `--hostname` and `--email` options
-in the installer). You can update your server's registration data by
-running `manage.py register_server` again.
-
-If you'd like to rotate your server's API key for this service
-(`zulip_org_key`), you need to use
-`manage.py register_server --rotate-key` option; it will automatically
-generate a new `zulip_org_key` and store that new key in
-`/etc/zulip/zulip-secrets.conf`.
-
-## Why this is necessary
 
 Both Google's and Apple's push notification services have a security
 model that does not support mutually untrusted self-hosted servers
@@ -160,24 +137,8 @@ and privacy in mind:
 - The push notification forwarding servers are professionally managed
   by a small team of security expert engineers.
 
-If you have any questions about the security model, contact
+If you have any questions about the security model, [contact Zulip
-support@zulip.com.
+support](https://zulip.com/help/contact-support).
-
-## Submitting statistics
-
-Systems using the Mobile Push Notifications Service will, by default,
-submit basic usage statistics (e.g. Zulip version, number of users,
-number of messages sent) to the service. These statistics help the
-Zulip open source project understand how many people are using Zulip,
-and help us allocate resources towards supporting self-hosted
-installations.
-
-Our use of these statistics is governed by the same [Terms of
-Service](https://zulip.com/policies/terms) and [Privacy
-Policy](https://zulip.com/policies/privacy) that covers the Mobile Push
-Notifications Service itself. If your organization does not want to submit these
-statistics, you can disable this feature at any time by setting
-`SUBMIT_USAGE_STATISTICS=False` in `/etc/zulip/settings.py`.
 
 ## Rate limits
 
@@ -193,6 +154,20 @@ anticipate that your server will require sending more push
 notifications than the limit permits, please [contact
 support](https://zulip.com/help/contact-support).
 
+## Updating your server's registration
+
+Your server's registration includes the server's hostname and contact
+email address (from `EXTERNAL_HOST` and `ZULIP_ADMINISTRATOR` in
+`/etc/zulip/settings.py`, aka the `--hostname` and `--email` options
+in the installer). You can update your server's registration data by
+running `manage.py register_server` again.
+
+If you'd like to rotate your server's API key for this service
+(`zulip_org_key`), you need to use
+`manage.py register_server --rotate-key` option; it will automatically
+generate a new `zulip_org_key` and store that new key in
+`/etc/zulip/zulip-secrets.conf`.
+
 ## Sending push notifications directly from your server
 
 This section documents an alternative way to send push notifications
@@ -205,25 +180,22 @@ mobile app can take dozens of hours to set up even for an experienced
 developer, and even more time to maintain. And it doesn't provide
 material privacy benefits -- your organization's push notification
 data would still go through Apple/Google's servers, just not Kandra
-Labs'. Our view is the correct way to optimize for privacy is
+Labs'. But in the interest of transparency, we document in this
-end-to-end encryption of push notifications. But in the interest of
+section roughly what's involved in doing so.
-transparency, we document in this section roughly what's involved in
-doing so.
 
-As we discussed above, it is impossible for a single app in their
+As [discussed above](#why-a-push-notification-service-is-necessary),
-stores to receive push notifications from multiple, mutually
+it is impossible for a single app in the Google or Apple
+store to receive push notifications from multiple, mutually
 untrusted, servers. The Mobile Push Notification Service is one of
-the possible solutions to this problem. The other possible solution
+the possible solutions to this problem.
-is for an individual Zulip server's administrators to build and
-distribute their own copy of the Zulip mobile apps, hardcoding a key
-that they possess.
 
-This solution is possible with Zulip, but it requires the server
+The other possible solution is for an individual Zulip server's administrators
-administrators to publish their own copies of
+to build and distribute their own copy of the Zulip mobile apps, hardcoding a
-the Zulip mobile apps (and there's nothing the Zulip team can do to
+key that they possess. This solution is possible with Zulip, but it requires the
-eliminate this onerous requirement).
+server administrators to publish their own copies of the Zulip mobile apps.
+There's nothing the Zulip team can do to eliminate this onerous requirement.
 
-The main work is distributing your own copies of the Zulip mobile apps
+The main work is thus distributing your own copies of the Zulip mobile apps
 configured to use APNS/FCM keys that you generate. This is not for
 the faint of heart! If you haven't done this before, be warned that
 one can easily spend hundreds of dollars (on things like a DUNS number