mbigras · August 17, 2025 16:27 · Nov 4, 2024 · Apr 26, 2023 · Jul 19, 2022 · Jul 19, 2022
diff --git a/nested-code-blocks.md b/nested-code-blocks.md
@@ -1,55 +1,55 @@
 # Nested code blocks
 
-> Nested code blocks clarify technical documentation but rendering them with markdown is tricky.
+> Nested code blocks organize technical documentation; but rendering them in Markdown is tricky. Luckily GitHub worked around the vague specification by making 4 space indentation "just work".
 
 ## Overview
 
-Google Cloud Platform (GCP) technical documentation is formatted well enough; however, emulating that format with markdown is tricky.
+Google Cloud Platform (GCP) technical documentation is formatted well enough; however, emulating that format in Markdown is tricky.
 
-The following are the main features about GCP documentation that I like:
+The following are the main organizational and formatting features about GCP documentation which I like:
 
 1. Headings name a procedure.
 1. Numerical lists describe the ordered steps of a procedure.
 1. Nested code blocks illustrate commands in a step.
 1. Nested bullets and/or nested paragraphs add relevant details about a given step.
 
-The important technique is _nesting_. When you nest your steps, commands, and details you organize complicated procedures as clear and manageable chunks. But problems arise when combining numerical lists, bulleted lists, code blocks, and paragraphs. The key technique is: use 3 spaces of indentation and code fences.
+The most important technique is _nesting_. When you nest your steps, commands, and details, you organize complicated procedures into clear and manageable chunks. But problems arise when combining numerical lists, bulleted lists, code blocks, and paragraphs. The key technique is: use 4 spaces of indentation and code fences.
 
 ## GCP example
 
-Consider the following example from the [Using Pub/Sub with Cloud Run tutorial](https://cloud.google.com/run/docs/tutorials/pubsub#setting-up-gcloud):
+Consider the following example from [Using Pub/Sub with Cloud Run tutorial](https://cloud.google.com/run/docs/tutorials/pubsub#setting-up-gcloud) page:
 
 ### Set up gcloud defaults
 
 To configure `gcloud` with defaults for your Cloud Run service:
 
 1. Set your default project:
 
-   ```
-   gcloud config set project $PROJECT_ID
-   ```
+    ```
+    gcloud config set project $PROJECT_ID
+    ```
 
-   Replace `$PROJECT_ID` with the name of the project you created for this tutorial.
+    Replace `$PROJECT_ID` with the name of the project you created for this tutorial.
 
 1. If you are using Cloud Run (fully managed), configure `gcloud` for your chosen region:
 
-   ```
-   gcloud config set run/region $REGION
-   ```
+    ```
+    gcloud config set run/region $REGION
+    ```
 
-   Replace `$REGION` with the supported Cloud Run region of your choice.
+    Replace `$REGION` with the supported Cloud Run region of your choice.
 
 1. If you are using Cloud Run for Anthos on Google Cloud, configure `gcloud` for your cluster:
 
-   ```
-   gcloud config set run/cluster $CLUSTER_NAME
-   gcloud config set run/cluster_location $REGION
-   ```
+    ```
+    gcloud config set run/cluster $CLUSTER_NAME
+    gcloud config set run/cluster_location $REGION
+    ```
 
-   Replace the following:
+    Replace the following:
 
-      1. `$CLUSTER_NAME` with the name you used for your cluster
-      1. `$REGION` with the supported cluster location of your choice
+    1. `$CLUSTER_NAME` with the name you used for your cluster
+    1. `$REGION` with the supported cluster location of your choice
 
 ## Discussion
 
@@ -63,4 +63,4 @@ The procedure is clear and ergonomic for readers for the following reasons:
 
 ## Implementation
 
-Sadly, this nested format favors the reader more than the writer. Problems arise when combining numerical lists, bulleted lists, code blocks, and paragraphs. The key technique is: use 3 spaces of indentation and code fences.
+Rendering nested code blocks in Markdown used to be really difficult; but luckily GitHub worked around the vague specification by making 4 space indentation "just work".
diff --git a/nested-code-blocks.md b/nested-code-blocks.md
@@ -8,12 +8,12 @@ Google Cloud Platform (GCP) technical documentation is formatted well enough; ho
 
 The following are the main features about GCP documentation that I like:
 
-* Headings name a procedure.
-* Numerical lists describe the ordered steps of a procedure.
-* Nested code blocks illustrate commands in a step.
-* Nested bullets and/or nested paragraphs add relevant details about a given step.
+1. Headings name a procedure.
+1. Numerical lists describe the ordered steps of a procedure.
+1. Nested code blocks illustrate commands in a step.
+1. Nested bullets and/or nested paragraphs add relevant details about a given step.
 
-The important technique is _nesting_. When you nest your steps, commands, and details you organize complicated procedures as clear and manageable chunks.
+The important technique is _nesting_. When you nest your steps, commands, and details you organize complicated procedures as clear and manageable chunks. But problems arise when combining numerical lists, bulleted lists, code blocks, and paragraphs. The key technique is: use 3 spaces of indentation and code fences.
 
 ## GCP example
 
@@ -48,18 +48,18 @@ To configure `gcloud` with defaults for your Cloud Run service:
 
    Replace the following:
 
-      * `$CLUSTER_NAME` with the name you used for your cluster
-      * `$REGION` with the supported cluster location of your choice
+      1. `$CLUSTER_NAME` with the name you used for your cluster
+      1. `$REGION` with the supported cluster location of your choice
 
 ## Discussion
 
 The procedure is clear and ergonomic for readers for the following reasons:
 
-* Foremost, the procedure is organized into manageable steps. Sometimes multiple commands belong in one step. The nested code blocks handle the situation fine.
-* Copy and paste is easy. I can select all or double click on a given command to copy and paste into my terminal.
-* There are no additional spaces or comments in the code blocks.
-* The variables are clear.
-* The difference between the description of a step, the actual command to run, and important details is clear.
+1. Foremost, the procedure is organized into manageable steps. Sometimes multiple commands belong in one step. The nested code blocks handle the situation fine.
+1. Copy and paste is easy. I can select all or double click on a given command to copy and paste into my terminal.
+1. There are no additional spaces or comments in the code blocks.
+1. The variables are clear.
+1. The difference between the description of a step, the actual command to run, and important details is clear.
 
 ## Implementation
 

diff --git a/nested-code-blocks.md b/nested-code-blocks.md
@@ -4,7 +4,7 @@
 
 ## Overview
 
-Google Cloud Platform (GCP) technical documentation is formatted well enough; however, emulating that GCP format with markdown is tricky.
+Google Cloud Platform (GCP) technical documentation is formatted well enough; however, emulating that format with markdown is tricky.
 
 The following are the main features about GCP documentation that I like:
 

diff --git a/nested-code-blocks.md b/nested-code-blocks.md
@@ -1,6 +1,6 @@
 # Nested code blocks
 
-> Nested code blocks clarify technical documentation but rendering nest code blocks with markdown is tricky.
+> Nested code blocks clarify technical documentation but rendering them with markdown is tricky.
 
 ## Overview
 

diff --git a/nested-code-blocks.md b/nested-code-blocks.md
@@ -1,19 +1,19 @@
 # Nested code blocks
 
-> Use nested code blocks for clear technical documentation.
+> Nested code blocks clarify technical documentation but rendering nest code blocks with markdown is tricky.
 
 ## Overview
 
-Google Cloud Platform (GCP) technical documentation is formatted well enough; however, emulating it with markdown is tricky.
+Google Cloud Platform (GCP) technical documentation is formatted well enough; however, emulating that GCP format with markdown is tricky.
 
-The following are the main features I like:
+The following are the main features about GCP documentation that I like:
 
-* Headings name a procdure
-* Numbered lists describe steps in a procedure
-* Nested code blocks illustrate commands in a given step
-* Nested bullets and/or nested paragraphs add important points about a given step
+* Headings name a procedure.
+* Numerical lists describe the ordered steps of a procedure.
+* Nested code blocks illustrate commands in a step.
+* Nested bullets and/or nested paragraphs add relevant details about a given step.
 
-The important technique is: _nesting_. Nesting steps, commands, and details organizes complicated procedures into clear chunks.
+The important technique is _nesting_. When you nest your steps, commands, and details you organize complicated procedures as clear and manageable chunks.
 
 ## GCP example
 

diff --git a/nested-code-blocks.md b/nested-code-blocks.md
@@ -1,4 +1,4 @@
-# Nested Code Blocks
+# Nested code blocks
 
 > Use nested code blocks for clear technical documentation.
 
@@ -15,11 +15,11 @@ The following are the main features I like:
 
 The important technique is: _nesting_. Nesting steps, commands, and details organizes complicated procedures into clear chunks.
 
-## GCP Example
+## GCP example
 
 Consider the following example from the [Using Pub/Sub with Cloud Run tutorial](https://cloud.google.com/run/docs/tutorials/pubsub#setting-up-gcloud):
 
-### Setting up gcloud defaults
+### Set up gcloud defaults
 
 To configure `gcloud` with defaults for your Cloud Run service:
 

diff --git a/nested-code-blocks.md b/nested-code-blocks.md
@@ -64,34 +64,3 @@ The procedure is clear and ergonomic for readers for the following reasons:
 ## Implementation
 
 Sadly, this nested format favors the reader more than the writer. Problems arise when combining numerical lists, bulleted lists, code blocks, and paragraphs. The key technique is: use 3 spaces of indentation and code fences.
-
-Consider this markdown source:
-
-```
-1. If you are using Cloud Run (fully managed), configure gcloud for your chosen region:
-
-   ```
-   gcloud config set run/region $REGION
-   ```
-
-   Replace `$REGION` with the supported Cloud Run region of your choice.
-
-1. If you are using Cloud Run for Anthos on Google Cloud, configure `gcloud` for your cluster:
-
-   ```
-   gcloud config set run/cluster $CLUSTER_NAME
-   gcloud config set run/cluster_location $REGION
-   ```
-
-   Replace the following:
-
-   * `$CLUSTER_NAME` with the name you used for your cluster
-   * `$REGION` with the supported cluster location of your choice
-```
-
-The following points are important:
-
-* Use the number `1.` for numbered lists because it makes adding new steps easier.
-* Use a newline, 3 spaces for indendation, and code fences for nested code blocks.
-   * It's not clear why 3 spaces instead of 4 spaces or a tab. Sometimes 4 or a tab will cause a space to appear in front of all the commands like ` echo foo`.
-* Use a newline and 3 spaces for indentation for nested lists and/or paragraphs.
diff --git a/nested-code-blocks.md b/nested-code-blocks.md
@@ -25,31 +25,31 @@ To configure `gcloud` with defaults for your Cloud Run service:
 
 1. Set your default project:
 
-    ```
-    gcloud config set project $PROJECT_ID
-    ```
+   ```
+   gcloud config set project $PROJECT_ID
+   ```
 
-    Replace `$PROJECT_ID` with the name of the project you created for this tutorial.
+   Replace `$PROJECT_ID` with the name of the project you created for this tutorial.
 
 1. If you are using Cloud Run (fully managed), configure `gcloud` for your chosen region:
 
-    ```
-    gcloud config set run/region $REGION
-    ```
+   ```
+   gcloud config set run/region $REGION
+   ```
 
-    Replace `$REGION` with the supported Cloud Run region of your choice.
+   Replace `$REGION` with the supported Cloud Run region of your choice.
 
 1. If you are using Cloud Run for Anthos on Google Cloud, configure `gcloud` for your cluster:
 
-    ```
-    gcloud config set run/cluster $CLUSTER_NAME
-    gcloud config set run/cluster_location $REGION
-    ```
+   ```
+   gcloud config set run/cluster $CLUSTER_NAME
+   gcloud config set run/cluster_location $REGION
+   ```
 
-    Replace the following:
+   Replace the following:
 
-    * `$CLUSTER_NAME` with the name you used for your cluster
-    * `$REGION` with the supported cluster location of your choice
+      * `$CLUSTER_NAME` with the name you used for your cluster
+      * `$REGION` with the supported cluster location of your choice
 
 ## Discussion
 
@@ -63,34 +63,35 @@ The procedure is clear and ergonomic for readers for the following reasons:
 
 ## Implementation
 
-Sadly, this nested format favors the reader more than the writer. Problems arise when combining numerical lists, bulleted lists, code blocks, and paragraphs. The key technique is: use 4 spaces of indentation and code fences.
+Sadly, this nested format favors the reader more than the writer. Problems arise when combining numerical lists, bulleted lists, code blocks, and paragraphs. The key technique is: use 3 spaces of indentation and code fences.
 
 Consider this markdown source:
 
 ```
 1. If you are using Cloud Run (fully managed), configure gcloud for your chosen region:
 
-    ```
-    gcloud config set run/region $REGION
-    ```
+   ```
+   gcloud config set run/region $REGION
+   ```
 
-    Replace `$REGION` with the supported Cloud Run region of your choice.
+   Replace `$REGION` with the supported Cloud Run region of your choice.
 
 1. If you are using Cloud Run for Anthos on Google Cloud, configure `gcloud` for your cluster:
 
-    ```
-    gcloud config set run/cluster $CLUSTER_NAME
-    gcloud config set run/cluster_location $REGION
-    ```
+   ```
+   gcloud config set run/cluster $CLUSTER_NAME
+   gcloud config set run/cluster_location $REGION
+   ```
 
-    Replace the following:
+   Replace the following:
 
-    * `$CLUSTER_NAME` with the name you used for your cluster
-    * `$REGION` with the supported cluster location of your choice
+   * `$CLUSTER_NAME` with the name you used for your cluster
+   * `$REGION` with the supported cluster location of your choice
 ```
 
 The following points are important:
 
 * Use the number `1.` for numbered lists because it makes adding new steps easier.
-* Use a newline, 4 spaces for indendation, and code fences for nested code blocks.
-* Use a newline and 4 spaces for indentation for nested lists and/or paragraphs.
+* Use a newline, 3 spaces for indendation, and code fences for nested code blocks.
+   * It's not clear why 3 spaces instead of 4 spaces or a tab. Sometimes 4 or a tab will cause a space to appear in front of all the commands like ` echo foo`.
+* Use a newline and 3 spaces for indentation for nested lists and/or paragraphs.
diff --git a/nested-code-blocks.md b/nested-code-blocks.md
@@ -53,7 +53,7 @@ To configure `gcloud` with defaults for your Cloud Run service:
 
 ## Discussion
 
-The procedure is clear and ergonomic for readers. I like this format for the following reasons:
+The procedure is clear and ergonomic for readers for the following reasons:
 
 * Foremost, the procedure is organized into manageable steps. Sometimes multiple commands belong in one step. The nested code blocks handle the situation fine.
 * Copy and paste is easy. I can select all or double click on a given command to copy and paste into my terminal.
@@ -63,7 +63,7 @@ The procedure is clear and ergonomic for readers. I like this format for the fol
 
 ## Implementation
 
-Sadly, this format favors the reader more than the writer. Problems arise when combining numerical lists, bulleted lists, code blocks, and paragraphs. The key technique is: use 4 spaces of indentation and code fences.
+Sadly, this nested format favors the reader more than the writer. Problems arise when combining numerical lists, bulleted lists, code blocks, and paragraphs. The key technique is: use 4 spaces of indentation and code fences.
 
 Consider this markdown source:
 

diff --git a/nested-code-blocks.md b/nested-code-blocks.md
@@ -15,9 +15,11 @@ The following are the main features I like:
 
 The important technique is: _nesting_. Nesting steps, commands, and details organizes complicated procedures into clear chunks.
 
+## GCP Example
+
 Consider the following example from the [Using Pub/Sub with Cloud Run tutorial](https://cloud.google.com/run/docs/tutorials/pubsub#setting-up-gcloud):
 
-## Setting up gcloud defaults
+### Setting up gcloud defaults
 
 To configure `gcloud` with defaults for your Cloud Run service:
 

diff --git a/nested-code-blocks.md b/nested-code-blocks.md
@@ -0,0 +1,94 @@
+# Nested Code Blocks
+
+> Use nested code blocks for clear technical documentation.
+
+## Overview
+
+Google Cloud Platform (GCP) technical documentation is formatted well enough; however, emulating it with markdown is tricky.
+
+The following are the main features I like:
+
+* Headings name a procdure
+* Numbered lists describe steps in a procedure
+* Nested code blocks illustrate commands in a given step
+* Nested bullets and/or nested paragraphs add important points about a given step
+
+The important technique is: _nesting_. Nesting steps, commands, and details organizes complicated procedures into clear chunks.
+
+Consider the following example from the [Using Pub/Sub with Cloud Run tutorial](https://cloud.google.com/run/docs/tutorials/pubsub#setting-up-gcloud):
+
+## Setting up gcloud defaults
+
+To configure `gcloud` with defaults for your Cloud Run service:
+
+1. Set your default project:
+
+    ```
+    gcloud config set project $PROJECT_ID
+    ```
+
+    Replace `$PROJECT_ID` with the name of the project you created for this tutorial.
+
+1. If you are using Cloud Run (fully managed), configure `gcloud` for your chosen region:
+
+    ```
+    gcloud config set run/region $REGION
+    ```
+
+    Replace `$REGION` with the supported Cloud Run region of your choice.
+
+1. If you are using Cloud Run for Anthos on Google Cloud, configure `gcloud` for your cluster:
+
+    ```
+    gcloud config set run/cluster $CLUSTER_NAME
+    gcloud config set run/cluster_location $REGION
+    ```
+
+    Replace the following:
+
+    * `$CLUSTER_NAME` with the name you used for your cluster
+    * `$REGION` with the supported cluster location of your choice
+
+## Discussion
+
+The procedure is clear and ergonomic for readers. I like this format for the following reasons:
+
+* Foremost, the procedure is organized into manageable steps. Sometimes multiple commands belong in one step. The nested code blocks handle the situation fine.
+* Copy and paste is easy. I can select all or double click on a given command to copy and paste into my terminal.
+* There are no additional spaces or comments in the code blocks.
+* The variables are clear.
+* The difference between the description of a step, the actual command to run, and important details is clear.
+
+## Implementation
+
+Sadly, this format favors the reader more than the writer. Problems arise when combining numerical lists, bulleted lists, code blocks, and paragraphs. The key technique is: use 4 spaces of indentation and code fences.
+
+Consider this markdown source:
+
+```
+1. If you are using Cloud Run (fully managed), configure gcloud for your chosen region:
+
+    ```
+    gcloud config set run/region $REGION
+    ```
+
+    Replace `$REGION` with the supported Cloud Run region of your choice.
+
+1. If you are using Cloud Run for Anthos on Google Cloud, configure `gcloud` for your cluster:
+
+    ```
+    gcloud config set run/cluster $CLUSTER_NAME
+    gcloud config set run/cluster_location $REGION
+    ```
+
+    Replace the following:
+
+    * `$CLUSTER_NAME` with the name you used for your cluster
+    * `$REGION` with the supported cluster location of your choice
+```
+
+The following points are important:
+
+* Use the number `1.` for numbered lists because it makes adding new steps easier.
+* Use a newline, 4 spaces for indendation, and code fences for nested code blocks.
+* Use a newline and 4 spaces for indentation for nested lists and/or paragraphs.