chore(doc): Update docs

docs/howto/flask-async.rst

@@ -1,28 +1,36 @@
-======================================================
-How to write a Kubernetes charm for an Async Flask app
+.. _write-a-kubernetes-charm-for-an-async-flask-app:
+
+How to write a Kubernetes charm for an async Flask app
 ======================================================
 
-In this how-to guide we will configure a 12-factor Flask
+In this how-to guide you will configure a 12-factor Flask
 application to use asynchronous Gunicorn workers to be
 able to serve to multiple users easily.
 
 Make the rock async
 ===================
 
-Before packing the rock make sure to put the following in ``requirements.txt``
+To make the rock async, make sure to put the following in its ``requirements.txt``
 file:
 
 .. literalinclude:: code/flask-async/requirements.txt
 
+Pack the rock using ``rockcraft pack`` and redeploy the charm with the new rock using
+[``juju refresh``](https://juju.is/docs/juju/juju-refresh).
+
 Configure the async application
-===============================
+-------------------------------
 
-Now let's enable async Gunicorn workers using a configuration option. We will
+Now let's enable async Gunicorn workers. We will
 expect this configuration option to be available in the Flask app configuration
-under the keyword ``webserver-worker-class``. Verify that the new configuration
-has been added using
-``juju config flask-async-app | grep -A 6 webserver-worker-class:`` which should
-show the configuration option.
+under the ``webserver-worker-class`` key. Verify that the new configuration
+has been added by running:
+
+.. code:: bash
+
+  juju config flask-async-app | grep -A 6 webserver-worker-class:
+
+The result should contain the key.
 
 The worker class can be changed using Juju:
 
@@ -32,23 +40,26 @@ The worker class can be changed using Juju:
     :end-before: [docs:config-async-end]
     :dedent: 2
 
-Now you can run
-``curl --parallel --parallel-immediate --resolve flask-async-app:80:127.0.0.1 \
-http://flask-async-app/io http://flask-async-app/io http://flask-async-app/io \
-http://flask-async-app/io http://flask-async-app/io``
+Test that the workers are operating in parallel by sending multiple
+simultaneous requests with curl:
+
+.. code:: bash
+
+  curl --parallel --parallel-immediate --resolve flask-async-app:80:127.0.0.1 \
+  http://flask-async-app/io http://flask-async-app/io http://flask-async-app/io \
+  http://flask-async-app/io http://flask-async-app/io
+
 and they will all return at the same time.
 
-Output will be similar to following:
+The results should arrive simultaneously and contain five instances of ``ok``:
 
-.. code-block:: bash
+.. terminal::
 
    ok
    ok
    ok
    ok
    ok
 
-.. note::
-
-    When the configuration is done the charm will be in ``active`` state.
-    It might take a short time for the configuration to take effect.
+It can take up to a minute for the configuration to take effect. When the
+configuration changes, the charm will re-enter the active state.