Apply suggestions from code review

Co-authored-by: William Lachance <wlachance@mozilla.com>
Co-authored-by: Anthony Miyaguchi <amiyaguchi@mozilla.com>

architecture/namespaces_yaml.md

@@ -1,14 +1,14 @@
-# Describing the formatting of `namespaces.yaml`
+# `namespaces.yaml`
 
-We use [`namespaces.yaml`](https://github.com/mozilla/looker-hub/blob/main/namespaces.yaml) as the declarative listing of what we will generate.
+We use [`namespaces.yaml`](https://github.com/mozilla/looker-hub/blob/main/namespaces.yaml) as the declarative listing of the Looker namespaces generated by this repository.
 
-Each namespace in `namespaces.yaml` has the following:
+Each entry in `namespaces.yaml` represents a namespace, and has the following properties:
 
 `owners` (string): The owners are the people who will have control over the associated Namespace folder in Looker. It is up to them to decide which dashboards to "promote" to their shared folder.
 `pretty_name` (string): The pretty name is used in most places where the namespace's name is seen, e.g. in the explore drop-down and folder name.
 `glean_app` (bool): Whether or not this namespace represents a Glean Application.
 `connection` (optional string): The database connection to use, as named in Looker. Defaults to `telemetry`.
-`views`: The LookML View files that will be generated. More detailed info below.
+`views` (object): The LookML View files that will be generated. More detailed info below.
 `explores`: The LookML Explore files that will be generated. More detailed info below.
 
 ## `views`
@@ -16,11 +16,11 @@ Each namespace in `namespaces.yaml` has the following:
 Each view is actuall a LookML view file that will be generated.
 Each LookML View file can contain multiple Looker Views; the idea here is that these views are related and used together.
 
-`type` - The type of the view, e.g. `glean_ping_view`.
-`tables` - This field is used in a few ways, depending on the associated View type.
+`type`: The type of the view, e.g. `glean_ping_view`.
+`tables`: This field is used in a few ways, depending on the associated View type.
 
 For `GleanPingView` and `PingView`, `tables` represents all of the associated channels for that view. Each table will have a `channel` and `table` entry. Only a single view will be created in the LookML File.
-```
+```yaml
 tables:
   - channel: release
     table: mozdata.org_mozilla_firefox.metrics
@@ -35,7 +35,7 @@ tables:
 ```
 
 For `FunnelAnalysisView`, only the first list entry is used; inside that entry, each value represents a Looker View that is created. The key is the name of the view, the value is the Looker View or BQ View it is derived from.
-In the following example, 4 views will be created in the view file. 
+In the following example, 4 views will be created in the view file: `funnel_analysis`, `event_types`, `event_type_1` and `event_type_2`. 
 ```
 tables:
   - funnel_analysis: events_daily_table
@@ -46,7 +46,7 @@ tables:
 
 ## `explores`
 
-Each Explore is a single Explore file, sometimes containing multiple explores within it (mainly for things like changing suggestions).
+Each Explore is a single file, sometimes containing multiple explores within it (mainly for things like changing suggestions).
 
 `type` - The type of the explore, e.g. `growth_accounting_explore`.
 `views` - The views that this is based on. Generally, the allowed keys here are: