Jump to Content
Application Development

Introducing interactive code samples in Google Cloud documentation

September 8, 2020
Cyrus Maden

Technical Writer

The Google Cloud documentation set has a new feature that makes it easier for you to run code samples that include placeholder variables. With this new feature, you can replace the variables inline, before you even copy the snippet. When you paste the text into your editor or into the command line, the values are already set!

https://storage.googleapis.com/gweb-cloudblog-publish/original_images/1_run_code_samples_that_include_placeholder_variables.gif

Placeholder variables

Placeholder variables represent custom parameter values—values in a code snippet that depend on your scenario or environment. The parameters might specify your credentials or the name of a resource.

https://storage.googleapis.com/gweb-cloudblog-publish/images/2_Placeholder_variables_cEMisZJ.max-700x700.jpg

With this new feature, you can replace the variables before copying the code sample. Edit variables in your browser, copy the command, and run it right away.

You'll often find placeholder variables in sample REST API calls and Cloud SDK commands, including the gcloud, bq, gsutil, and kubectl samples. How can you tell if a variable is editable? Look for the pencil icon and the dotted underline.

https://storage.googleapis.com/gweb-cloudblog-publish/images/3_editable_commands.max-1300x1300.jpg

Edit one sample, run them all

If a page has multiple code samples with the same placeholder variable, you only need to replace the variable once. For example, when you replace a PROJECT_ID variable with your own Google Cloud project ID, all instances of the PROJECT_ID variable (including in any other command line samples on the page) will use the same Google Cloud project ID.

https://storage.googleapis.com/gweb-cloudblog-publish/original_images/4_Google_Cloud_project_ID.gif

Preview successful API calls

Documentation often shows the results of an API call. For example, when we show REST API calls, we usually show sample responses from a server. The placeholder variables in the responses stay in sync with the variables in the examples.

https://storage.googleapis.com/gweb-cloudblog-publish/images/5_Preview_successful_API_calls.max-1700x1700.jpg

You can make sure your REST API calls are successful by comparing the response you get with the sample. Replace the variables in the example, make the API call, and check the response at a glance.

Try it out

You can find the interactive code samples throughout Google Cloud documentation. To try out the new feature, you can create a Cloud Storage bucket using the gsutil command-line tool or REST API.

Posted in