docs: Reword pgroonga sections.

These were somewhat stilted as originally written; reword.

docs/subsystems/full-text-search.md

@@ -25,75 +25,62 @@ updating is done by
 deployed on the database server, but could be deployed on an
 application server instead.
 
-## An optional full-text search implementation
+## Multi-language full-text search
 
-Zulip now supports using [PGroonga](https://pgroonga.github.io/) for
+Zulip also supports using [PGroonga](https://pgroonga.github.io/) for
-full-text search. PGroonga is a PostgreSQL extension that provides
+full-text search. While PostgreSQL's built-in full-text search feature
-full-text search feature. PostgreSQL's built-in full-text search
+supports only one language at a time (in Zulip's case, English), the
-feature supports only one language at a time (in Zulip's case,
+PGroonga full-text search engine supports all languages
-English).  PGroonga supports all languages simultaneously, including
+simultaneously, including Japanese and Chinese.  Once we have tested
-Japanese, Chinese and so on, all at once.  We expect to migrate
+this new backend sufficiently, we expect to switch Zulip deployments
-Zulip's full-text search to only support PGroonga once we have tested
+to always use PGroonga.
-this new extension fully.
 
-The following processes should be executed as the root user. Run:
+### Enabling PGroonga
 
-    sudo -i
+All steps in this section should be run as the `root` user; on most installs, this can be done by running `sudo -i`.
 
-### How to enable full-text search across all languages
+1. Alter the deployment setting:
 
-This section describes how to enable using PGroonga to back the
+        crudini --set /etc/zulip/zulip.conf machine pgroonga enabled
-full-text search feature.
 
-To install PGroonga, add `pgroonga = enabled` in the `[machine]`
+1. Update the deployment to respect that new setting:
-section in `/etc/zulip/zulip.conf`:
 
-    [machine]
+        /home/zulip/deployments/current/scripts/zulip-puppet-apply
-    ...
-    pgroonga = enabled
 
-And then run as root:
+1. Edit `/etc/zulip/settings.py`, to add:
 
-    /home/zulip/deployments/current/scripts/zulip-puppet-apply
+        USING_PGROONGA = True
 
-Then, add `USING_PGROONGA = True` in `/etc/zulip/settings.py`:
+1. Apply the PGroonga migrations:
 
-    USING_PGROONGA = True
+        su zulip -c '/home/zulip/deployments/current/manage.py migrate pgroonga'
 
-And apply the PGroonga migrations:
+    Note that the migration may take a long time, and users will be
+    unable to send new messages until the migration finishes.
 
-    su zulip -c '/home/zulip/deployments/current/manage.py migrate pgroonga'
+1. Once the migrations are complete, restart Zulip:
 
-Note that the migration may take a long time, and you can't send new
+        su zulip -c '/home/zulip/deployments/current/scripts/restart-server'
-messages until the migration finishes.
 
-Once the migrations are complete, restart Zulip:
 
-    su zulip -c '/home/zulip/deployments/current/scripts/restart-server'
+### Disabling PGroonga
 
-Now, you can use full-text search across all languages.
+1. Remove the PGroonga migration:
 
-### How to disable full-text search across all languages
+        su zulip -c '/home/zulip/deployments/current/manage.py migrate pgroonga zero'
 
-This section describes how to disable full-text search feature based
+    If you intend to re-enable PGroonga later, you can skip this step,
-on PGroonga.
+    at the cost of your Message table being slightly larger than it would
+    be otherwise.
 
-If you want to fully remove PGroonga, first you need to remove the
+1. Edit `/etc/zulip/settings.py`, editing the line containing `USING_PGROONGA` to read:
-PGroonga column (as above, this will take a long time and no messages
-can be sent while it is running).  If you intend to re-enable PGroonga
-later, you can skip this step (at the cost of your Message table being
-slightly larger than it would be otherwise).
 
-    su zulip -c '/home/zulip/deployments/current/manage.py migrate pgroonga zero'
+        USING_PGROONGA = False
 
-Then, set `USING_PGROONGA = False` in `/etc/zulip/settings.py`:
+1. Restart Zulip:
 
-    USING_PGROONGA = False
+        su zulip -c '/home/zulip/deployments/current/scripts/restart-server'
 
-And, restart Zulip:
+1. Finally, remove the deployment setting:
 
-    su zulip -c '/home/zulip/deployments/current/scripts/restart-server'
+        crudini --del /etc/zulip/zulip.conf machine pgroonga
-
-Now, full-text search feature based on PGroonga is disabled.  If you'd
-like, you can also remove the `pgroonga = enabled` line in
-`/etc/zulip/zulip.conf` and uninstall the `pgroonga` packages.