docs: another pass on library-howto (#11880)

coryan · web-flow · commit b3b599865ab2 · 2023-06-13T13:29:51.000-04:00
diff --git a/doc/contributor/howto-guide-adding-generated-libraries.md b/doc/contributor/howto-guide-adding-generated-libraries.md
@@ -23,6 +23,7 @@ cd $HOME/google-cloud-cpp
 ```shell
 library=... # The name of your new library in the google-cloud-cpp repository
 subdir="google/cloud/${library}"  # The path in googleapis repo, may not start with google/cloud/
+bazel_output_base="$(bazel info output_base)"
 ```
 
 ## Verify the C++ rules exist
@@ -70,6 +71,13 @@ example, [here][retryable-status-codes].
 
 Manually edit `generator/generator_config.textproto` and add the new service.
 
+Find the list of `.proto` files that will need to be included:
+
+```shell
+find "${bazel_output_base}/external/com_google_googleapis/${subdir}" -name '*.proto' -print0 |
+  xargs -0 grep -l '^service'
+```
+
 > **Note:**
 > While older service definitions may not include the version specification
 > in the `product_path` field, all new services are required to include the
@@ -119,7 +127,6 @@ external/googleapis/update_libraries.sh "${library}"
 Then run the micro-generator to create the scaffold and the C++ sources:
 
 ```shell
-bazel_output_base="$(bazel info output_base)"
 bazel run \
   //generator:google-cloud-cpp-codegen -- \
   --protobuf_proto_path="${bazel_output_base}"/external/com_google_protobuf/src \
@@ -184,25 +191,14 @@ Otherwise, if you are generating an experimental library, add it to
 `GOOGLE_CLOUD_CPP_EXPERIMENTAL_LIBRARIES` and note in a comment when the library
 was generated.
 
-## Add the API baseline
-
-For new GA libraries you need to create the API baseline.  You can leave this
-running while you work on tweaks to the quickstart and documentation.
-
-```shell
-env GOOGLE_CLOUD_CPP_CHECK_API=${library} ci/cloudbuild/build.sh -t check-api-pr
-git add ci/abi-dumps
-git commit -m"Add API baseline" ci/abi-dumps/
-```
-
 ## Update the quickstart
 
 The generated quickstart will need some editing. Use a simple operation, maybe
 an admin operation listing top-level resources, to demonstrate how to use the
 API. Test your changes with:
 
 ```sh
-gcloud services enable --project=cloud-cpp-testing-resources ${lbrary}.googleapis.com
+gcloud services enable --project=cloud-cpp-testing-resources "${library}.googleapis.com"
 bazel run -- //google/cloud/${library}/quickstart:quickstart $params
 ```
 
@@ -211,6 +207,17 @@ arguments in the CI builds.
 
 - `google/cloud/${library}/CMakeLists.txt`
 
+## Add the API baseline
+
+For new GA libraries you need to create the API baseline.  You can leave this
+running while you work on tweaks to the quickstart and documentation.
+
+```shell
+env GOOGLE_CLOUD_CPP_CHECK_API=${library} ci/cloudbuild/build.sh -t check-api-pr
+git add ci/abi-dumps
+git commit -m"Add API baseline" ci/abi-dumps/
+```
+
 ## Update the README files
 
 The following files probably need some light copy-editing to read less like they
