diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md
index 8261b8b93..c849221a2 100644
--- a/docs/use-psa-crypto.md
+++ b/docs/use-psa-crypto.md
@@ -4,17 +4,17 @@ This document describes the compile-time configuration option
 This option makes the X.509 and TLS library use PSA for cryptographic
 operations, and enables new APIs for using keys handled by PSA Crypto.
 
-General limitations
--------------------
+General considerations
+----------------------
 
-Compile-time: enabling `MBEDTLS_USE_PSA_CRYPTO` requires
+**Compile-time:** enabling `MBEDTLS_USE_PSA_CRYPTO` requires
 `MBEDTLS_ECP_RESTARTABLE` to be disabled.
 
-Application code: when this option is enabled, you need to call
+**Application code:** when this option is enabled, you need to call
 `psa_crypto_init()` before calling any function from the SSL/TLS, X.509 or PK
 module.
 
-Scope: `MBEDTLS_USE_PSA_CRYPTO` has no effect on the parts of the code that
+**Scope:** `MBEDTLS_USE_PSA_CRYPTO` has no effect on the parts of the code that
 are specific to TLS 1.3; those parts always use PSA Crypto. The parts of the
 TLS 1.3 code that are common with TLS 1.2, however, follow this option;
 currently this is the record protection code, computation of the running
@@ -26,42 +26,42 @@ New APIs / API extensions
 
 ### PSA-held (opaque) keys in the PK layer
 
-There is a new API function `mbedtls_pk_setup_opaque()` that can be used to
-wrap a PSA keypair into a PK context. The key can be used for private-key
+**New API function:** `mbedtls_pk_setup_opaque()` - can be used to
+wrap a PSA key pair into a PK context. The key can be used for private-key
 operations and its public part can be exported.
 
-Benefits: isolation of long-term secrets, use of PSA Crypto drivers.
+**Benefits:** isolation of long-term secrets, use of PSA Crypto drivers.
 
-Limitations: can only wrap a keypair, can only use it for private key
+**Limitations:** can only wrap a key pair, can only use it for private key
 operations. (That is, signature generation, and for RSA decryption too.)
 Note: for ECDSA, currently this uses randomized ECDSA while Mbed TLS uses
 deterministic ECDSA by default. The following operations are not supported
 with a context set this way, while they would be available with a normal
-`mbedtls_pk_check_pair()`, `mbedtls_pk_debug()`, all public key operations.
+context: `mbedtls_pk_check_pair()`, `mbedtls_pk_debug()`, all public key
+operations.
 
-Use in X.509 and TLS: opt-in. The application needs to construct the PK context
+**Use in X.509 and TLS:** opt-in. The application needs to construct the PK context
 using the new API in order to get the benefits; it can then pass the
 resulting context to the following existing APIs:
 
 - `mbedtls_ssl_conf_own_cert()` or `mbedtls_ssl_set_hs_own_cert()` to use the
-  key together with a certificate for ECDSA-based key exchanges (note: while
-this is supported on both sides, it's currently only tested client-side);
+  key together with a certificate for certificate-based key exchanges;
 - `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature
-  request).
+  request);
 - `mbedtls_x509write_crt_set_issuer_key()` to generate a certificate.
 
 ### PSA-held (opaque) keys for TLS pre-shared keys (PSK)
 
-There are two new API functions `mbedtls_ssl_conf_psk_opaque()` and
+**New API functions:** `mbedtls_ssl_conf_psk_opaque()` and
 `mbedtls_ssl_set_hs_psk_opaque()`. Call one of these from an application to
 register a PSA key for use with a PSK key exchange.
 
-Benefits: isolation of long-term secrets.
+**Benefits:** isolation of long-term secrets.
 
-Limitations: only TLS 1.2 for now.
+**Limitations:** none.
 
-Use in TLS: opt-in. The application needs to register the key using the new
-APIs to get the benefits.
+**Use in TLS:** opt-in. The application needs to register the key using one of
+the new APIs to get the benefits.
 
 ### PSA-based operations in the Cipher layer
 
@@ -72,8 +72,9 @@ This function only worked for a small number of ciphers. It is now deprecated
 and it is recommended to use `psa_cipher_xxx()` or `psa_aead_xxx()` functions
 directly instead.
 
-This function will be removed in a future version of Mbed TLS. If you are using
-it and would like us to keep it, please let us know about your use case.
+**Warning:** This function will be removed in a future version of Mbed TLS. If
+you are using it and would like us to keep it, please let us know about your
+use case.
 
 Internal changes
 ----------------
@@ -85,8 +86,8 @@ is enabled, no change required on the application side.
 
 Current exceptions:
 
-- EC J-PAKE (when `MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED`)
-- finite-field (non-EC) Diffie-Hellman (use in key exchanges: DHE-RSA,
+- EC J-PAKE (when `MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED` is defined)
+- finite-field (non-EC) Diffie-Hellman (used in key exchanges: DHE-RSA,
   DHE-PSK)
 
 Other than the above exceptions, all crypto operations are based on PSA when