WIP++

src/current/v24.3/configure-replication-zones.md

@@ -78,35 +78,37 @@ When replicating data, whether table or system, CockroachDB always uses the most
 1. If there's no applicable table replication zone, CockroachDB uses the [database replication zone](#create-a-replication-zone-for-a-database).
 1. If there's no applicable database replication zone, CockroachDB uses [the `default` cluster-wide replication zone](#view-the-default-replication-zone).
 
-For more information about how level priorities work in detail, see the section [How zone config inheritance works](#how-zone-config-inheritance-works).
+As this example shows, CockroachDB chooses which replication zone applies to a specific schema object using a hierarchy of inheritance. For most users [who never modify their zone configurations](#why-manual-zone-config-management-is-not-recommended), this level of understanding is sufficient.
+
+However, there are nuances in how inheritance works that are not explained by this example. For more details about how zone config inheritance works, see the section [How zone config inheritance works](#how-zone-config-inheritance-works).
 
 ### How zone config inheritance works
 
-As [discussed previously](#level-priorities), CockroachDB always uses the most granular replication zone available for each schema object (database, table, etc.). More-specific settings applied to schema objects at lower levels of the inheritance tree will always override the settings of objects above them in the tree. All configurations will therefore be modified versions of the [`default` range]({% link {{ page.version.version }}/configure-replication-zones.md %}#view-the-default-replication-zone), which acts as the root of the tree. This means that in practice, any changes to a specific schema object's zone configuration values are by definition user-initiated, either via [Multi-region SQL abstractions]({% link {{ page.version.version }}/multiregion-overview.md %}) or manual changes using [`CONFIGURE ZONE`]({% link {{ page.version.version }}/alter-database.md %}#configure-zone).
+As [discussed previously](#level-priorities), CockroachDB always uses the most granular replication zone available for each schema object (database, table, etc.). More-specific settings applied to schema objects at lower levels of the inheritance tree will always override the settings of objects above them in the tree. All configurations will therefore be modified versions of the [`default` range]({% link {{ page.version.version }}/configure-replication-zones.md %}#view-the-default-replication-zone), which acts as the root of the tree. This means that in practice, **any changes to a specific schema object's zone configurations are by definition user-initiated**, either via [Multi-region SQL abstractions]({% link {{ page.version.version }}/multiregion-overview.md %}) or [manual changes](#why-manual-zone-config-management-is-not-recommended).
 
-Because each zone config inherits all of its initial values from its parent object, **it only stores the values that differ from its parent**. Any fields that are unset will be looked up in the parent object’s zone configuration. This continues recursively up the inheritance hierarchy all the way to the `default` zone config. (Note that in practice most values are cached to avoid performance impacts.)
+Because each zone config inherits all of its initial values from its parent object, **it only stores the values that differ from its parent**. Any fields that are unset will be looked up in the parent object’s zone configuration. This continues recursively up the inheritance hierarchy all the way to the `default` zone config. (In practice, most values are cached for performance.)
 
 For more information, see the following subsections:
 
 - [The zone config inheritance hierarchy](#the-zone-config-inheritance-hierarchy)
-- [The "bottom-up" view of inheritance](#the-bottom-up-view-of-inheritance)
-- [The "top-down" view of inheritance](#the-top-down-view-of-inheritance)
 - [Why manual zone config management is not recommended](#why-manual-zone-config-management-is-not-recommended)
 - [Zone config inheritance - example SQL session](#zone-config-inheritance-example-sql-session)
 
 #### The zone config inheritance hierarchy
 
 The hierarchy of inheritance for zone configs can be visualized using the following outline-style diagram, in which each level of indentation denotes an inheritance relationship.
 
+The only exception to this simple picture is that due to a known limitation, sub-partitions do not inherit their values from their parent partitions. Instead, sub-partitions inherit their values from the parent table. For more information, see [cockroachdb/cockroach#75862](https://github.com/cockroachdb/cockroach/issues/75862).
+
 ```
 - default
   - database
     - table
       - index
-        - partition (row) A
-          - (sub)partition A.1 (NB. Subpartitions inherit from tables, *not* partitions - see cockroachdb/cockroach#75862)
-            - (sub)partition A.1.1
-          - (sub)partition A.2
+        - partition (row) 1
+          - sub-partition 1.1 (NB. Sub-partitions inherit from tables, *not* partitions - see cockroachdb/cockroach#75862)
+            - sub-partition 1.1.1
+          - sub-partition 1.2
     - table
       - index
       - index
@@ -115,33 +117,25 @@ The hierarchy of inheritance for zone configs can be visualized using the follow
 
 The way the zone config inheritance hierarchy works can be thought of from a ["bottom-up"](#the-bottom-up-view-of-inheritance) or ["top-down"](#the-top-down-view-of-inheritance) perspective; both are useful, and which is easier to understand depends on what you are doing.
 
-#### The "bottom-up" view of inheritance
-
 The "bottom-up" view of how zone config inheritance works is useful when you [start a troubleshooting session by looking at a specific schema object's zone configurations](XXX).
 
-In this view, you start with the schema object that currently interests you (generally, the one you think is misconfigured). You start at its current level in the inheritance tree, looking at the specific state of its configuration (namely, what is different about it from its parent?), and work upwards.
-
-
-#### The "top-down" view of inheritance
-
-[XXX](XXX): REVISE ME
+In this view, you start with the most granular schema object whose replication behavior currently interests you. In a troubleshooting session, this is usually the one you think is misconfigured. You start at the schema object's current level in the inheritance tree, looking at the specific state of its configuration to see what is different about it from its parent schema object (if anything), and work upwards from there.
 
-The "top-down" perspective of how zone config inheritance works is useful when thinking about the system as a whole.
+[XXX](XXX): YOU ARE HERE
 
-Given the the tree of schema object zone configs, the system does a depth-first traversal down the tree and, for each node, **uses the value of the most specific modified field from the current node's zone config**, unless or until it finds a modifed value of that same field on a node further down the tree. For each field on the current node's zone config where it doesn't find any modified value, it inherits that value from the node's parent, which inherits from its parent, and so on all the way back up to the root of the tree ([the `default` range](#view-the-default-replication-zone)).
+The "top-down" perspective of how zone config inheritance works is useful when thinking about how the system works as a whole.
 
-The following diagram presents the same set of schema objects as [the ASCII diagram in the previous section](#the-zone-config-inheritance-hierarchy), but using boxes and lines joined with arrows that represent the "top-down" view. 
+The hierarchy of schema object zone configs can be thought of as a tree. From this perspective, how the system works conceptually is that it does a depth-first traversal down the tree and, for each node, **uses the value of the most specific modified field from the current node's zone config, unless or until it finds a modifed value of that same field on a node further down the tree**. For each field on the current node's zone config where it doesn't find any modified value, it uses the inherited value from the node's parent, which inherits from its parent, and so on all the way back up to the root of the tree ([the `default` range](#view-the-default-replication-zone)).
 
-Each box represents a schema object's zone configuration, and each line points from a parent object to its child objects, which will inherit the parent's values unless those values are changed at the child level. The dotted lines between (sub)partitions (a.k.a., rows) represent the fact that sub-partitions do not inherit their values from their parent partitions. Instead, subpartitions inherit their values from the parent table. For more information, see [cockroachdb/cockroach#75862](https://github.com/cockroachdb/cockroach/issues/75862).
+The following diagram presents the same set of schema objects as the previous outline-style diagram, but using boxes and lines joined with arrows that represent the "top-down" view. 
 
-[XXX](XXX): SHOULD THE ABOVE (cockroachdb/cockroach#75862) BE CONSIDERED A "KNOWN LIMITATION" AND ADDED TO THAT PAGE???
-[XXX](XXX): FILE DOCS ISSUE RE: cockroachdb/cockroach#75862 AND LINK ZD ISSUE FROM cockroachlabs/support#3143
+Specifically, each box represents a schema object in the zone configuration inheritance hierarchy. Each solid line ends in an arrow that points from the parent object to its child object, which will inherit the parent's values unless those values are changed at the child level. The dotted lines between partitions and sub-partitions represent the known limitation mentioned previously that sub-partitions do not inherit their values from their parent partitions. Instead, sub-partitions inherit their values from the parent table. For more information about this limitation, see [cockroachdb/cockroach#75862](https://github.com/cockroachdb/cockroach/issues/75862).
 
 <img src="{{ 'images/v24.3/zone-config-inheritance-diagram.png' | relative_url }}" alt="zone config inheritance diagram" style="border:1px solid #eee;max-width:100%" />
 
 #### Why manual zone config management is not recommended
 
-Reasons to avoid modifying zone configurations manually include:
+Reasons to avoid modifying zone configurations manually using [`CONFIGURE ZONE`]({% link {{ page.version.version }}/alter-database.md %}#configure-zone) include:
 
 - It is difficult to do proper auditing and change management of manually altered zone configurations.
 - It is easy to introduce logic errors (a.k.a., bugs) and end up in a state where your replication is not behaving as it is "supposed to".

src/current/v24.3/troubleshoot-replication-zones.md

@@ -48,6 +48,8 @@ If you just did a [cluster restore]({% link {{ page.version.version }}/restore.m
 
 ### Step 1. Start with target object and see what changed
 
+
+
 ### Step 2. Move upward in the inheritance hierarchy as needed
 
 ### Step 3. Confirm invalid replication behavior using critical nodes endpoint