Use nested code blocks for clear technical documentation.

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:

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.

2. 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.

3. 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 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.

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.