Improve layout

docs/source/how-to/helm.md

@@ -49,8 +49,8 @@ kubectl apply -f secret.yaml
 ## Further Configuration
 
 A common pattern for managing the configuration of a Helm chart is to wrap the config
-as another layer of chart, with the bundled instance configuration and the dependent
-charts kept under source control.
+as another layer of chart: an "Umbrella Chart" under which is the instance configuration 
+and the dependent charts are kept together in source control.
 
 ```
 (
@@ -62,7 +62,7 @@ charts kept under source control.
 ```
 
 The dependent chart(s): tiled and any other services that *should live and die with the
-tiled instance* can be referenced from the Chart.yaml:
+tiled instance* are referenced from the Chart.yaml:
 
 ```yaml
 apiVersion: v2
@@ -84,8 +84,8 @@ dependencies:
 While overrides for the bundled values.yaml in each dependency chart can be passed
 as part of the values.yaml.
 
-Note that the `name` in the `dependencies` in the Chart.yaml give the top-level key
-to use in the values.yaml:
+Note that the `name` (or `alias`) in the `dependencies` in the Chart.yaml give the top-level
+key to use in the values.yaml:
 
 ```yaml
 tiled:
@@ -99,9 +99,7 @@ example the SealedSecret defined above.
 
 ## Deploying with oauth2-proxy
 
-Deploying behind a reverse proxy that redirects unauthenticated requests to your OAuth2/OIDC provider places a layer of security in front of the tiled API, and allows authenticated requests in the web frontend with a full OIDC flow on your provider's login page.
-
-Configure your OAuth2 client values, referencing back to the Quickstart guide for how to configure a SealedSecret in your templates directory.
+Deploying behind a reverse proxy that redirects unauthenticated requests to your OAuth2 provider places a layer of security in front of the tiled API, and allows authenticated requests in the web frontend with a full OAuth2 flow on your provider's login page.
 
 ```{note}
 The following assumes that your tiled installation is configured with an umbrella chart as described in the Further Configuration section.
@@ -121,7 +119,7 @@ dependencies:
     repository: "https://oauth2-proxy.github.io/manifests"
 ```
 
-Add required configuration as SealedSecrets as appropriate.
+Add required OAuth2 configuration to your SealedSecret.
 
 ```yaml
 apiVersion: bitnami.com/v1alpha1
@@ -149,7 +147,7 @@ oauth2-proxy:
       valueFrom:
         secretKeyRef:
           name: tiled-secrets
-          key: client-secret
+          key: CLIENT_SECRET
   ingress: {}  # Configure your Ingress/LoadBalancer to point to the oauth2-proxy pod
   config:
     configFile: |-  # Cannot be empty else tries to define invalid upstreams
@@ -173,7 +171,8 @@ oauth2-proxy:
 
 ```
 
-Configure tiled to use an OAuth2 compatible authentication method, such as the OIDCAuthenticator
+You may aslo configure tiled to use an OAuth2 compatible authentication method, such as the 
+OIDCAuthenticator, configured for the same OAuth2 provider.
 
 ```yaml
 tiled:
@@ -184,7 +183,7 @@ tiled:
       valueFrom:
         secretKeyRef:
           name: tiled-secrets
-          key: client-secret
+          key: CLIENT_SECRET
 
   config:
     authentication:
@@ -198,3 +197,4 @@ tiled:
           client_secret: ${CLIENT_SECRET}
           well_known_uri: https://example.com/.well-known/openid-configuration
           confirmation_message: "You have logged in with example.com as {id}."
+```