Creating Google Cloud Shell Tutorials

I love creating developer tutorials. A majority of the time, I end up writing them as blog posts (fairly detailed ones) and I do my best to not miss a step and give screenshots of what to expect along the way.

Given the pace at which new versions of software are being released, I often play a losing game when it comes to keeping my material updated. Is there a better experience that I can give my readers that is cognizant of the fact that they would simply like to get going quickly, have the code ready, just see it all work and it has just about enough instructions and theory. One approach can be creating videos but I find those difficult to update too.

A recently released feature on Google Cloud Platform allows you to create a tutorial that runs inside Google Cloud Shell. This definitely opens up multiple possibilities and all I need to do to keep this tutorial updated is probably minimal text changes and code updates. I think it has very good potential and I am excited about it.

This blog post will be about how to go about creating tutorials that provide a seamless experience to the user in terms of packaging all the code necessary to run your tutorial, provision that on the Cloud Shell and provide step by step instructions that helps the reader follow along, in true tutorial style.

Cloud Shell Tutorial in Action

Let us first look at what we are trying to do here. That will make things much easier to understand when it comes to writing a tutorial similar to the one that you will shortly see.

The only prerequisites to running this tutorial is to have a GCP Account.

Please visit the following URL:

When you visit the above page, you will be led to the README.md file, a snippet of which is shown below:

When you visit the above page, you will be led to the README.md file, a snippet of which is shown below:

I have tried to demonstrate how to write a tutorial that runs in Google Cloud Shell and teaches you about the Google Cloud Natural Language API via an experience that looks like a codelab but goes a step further setting up all the code for you in Cloud Shell for you to get running quickly.

You do not need to run the whole tutorial, just a few steps will do to give you a good idea of what’s going on.

Click on the blue button titled “Open in Google Cloud Shell”. What happens next is magical.

It uses your Google Cloud Platform account and launches Google Cloud Shell and asks you for permission to clone the Git Repo as shown below. Click on PROCEED.

It then moves forward to setting up a Workspace for you as shown below.

If everything goes well, you will have a Cloud Shell session that looks like this:

1. Workspace with the folders/files cloned from the project.
2. The Cloud Shell terminal with the current directory set to the folder in which the project was cloned.
3. The step by step tutorial is launched for you on the right. It contains the instructions that you give and you can proceed with the tutorial by click on the blue Continue button.

Give it a try and go through the next few steps and if you actually try them out in the terminal session, you will even learn about the Cloud Natural Language API :-)

Tutorial Plan

Before we dive into the tutorial creation specifics, let’s remind ourselves of a quote.

No battle was ever won according to plan, but no battle was ever won without one — Dwight D. Eisenhower

I cannot stress enough the importance of planning out your tutorial. Even if you have never created a step by step tutorial before, put down a rough set of steps. For e.g. Each of the numbers below could be a step in the tutorial.

1. What is this tutorial about ?
2. What are the prerequisites?
3. What setup do we have to do before inspecting code?
4. Browse through the code and explain it
5. Instructions on compiling the code
6. Executing the code
7. A few points to summarize the learnings
8. Conclusion

Hopefully you get the picture. What works for me is to actually put down the above points as sections and then fill them out accordingly with text, source code, instructions to build/run and so on. These are just my recommendations but you should go with your flow and how you would like to write the tutorial.

Create the Outline

The tutorial that you shall create will go into a single (CommonMark) Markdown syntax file. Let us call this file tutorial.md. The tutorial can be thought of conceptually as having the following:

• Title
• One or more sections
• Each Section can have multiple sub-sections (or topics)

A sample tutorial.md file is shown below:

# Tutorial on Google Natural Language API
## Google Natural Language API (STEP 1)
    … some text … 
    ### Prerequisites
## Service Account Creation (STEP 2)
## Use npm to install dependencies (STEP 3)
## Source Code (STEP 4)
## Run the application (STEP 5)
## Conclusion (STEP 6)
### Next Steps: (STEP 7)

The syntax supports the H1 (#) , H2 (##) and H3 (###) tags for notifying the title of the tutorial, the steps in the tutorial and the substeps respectively. That’s all there is to it. There can only be one title tag (#) in the entire tutorial.

Step Details

Now that you have the outline in place, all you need to do is fill out the details in each of the steps and substeps. Note that the title tags i.e. ## and ## will determine the title i.e. label of the steps and what follows them is what will be displayed on the that particular step page in tutorial.

It is obvious that we can put in as much text as we want. But what are the other elements that it supports. The tool creators have thought about it carefully and have come up with initial support for multiple custom elements that will keep the user experience in mind i.e. make it easier for the reader to click at certain points on the screen (icons) by highlighting them, opening up files in the editor and so on.

Let us discuss a few of these elements:

Code block

Let us take a particular step from my complete tutorial.md file. A part of the rendered tutorial step is shown below:

You should now be able to easily predict that it consists of :

1. A Step Title
2. Some text
3. Code Block

The code snippet to support that is shown below:

## Service Account Creation
First up, let’s create an environment variable to store your Project Id. Please use the code snippet below to set the `PROJECT_ID` variable as given below:
```bash
export PROJECT_ID=<your_project_id>
```

The Title for the Step is via the H2 (##) tag. The text is standard stuff and the way you include any code block is via the ```bash ….. ``` element as shown above.

The great part about this is that it is rendered as shown below with a Copy icon at the extreme right corner. The user can click on this, which copies the command to the clipboard and you can paste that into the Shell terminal session easily. Little things like this make a big difference.

Note: You can have as many code blocks in a step as you like.

Trigger a file open

This is an interesting element which helps you to open the file directly in the Orion editor that is integrated into the Cloud Shell Workspace. Take a look at a particular step in the tutorial as shown below:

The code snippet for this is shown below:

## Source Code
Let us go through the JavaScript file to understand the source code.
Click here: `walkthrough editor-open-file “Google-Cloud-Shell-Tutorial-Creation/index.js” “Open index.js”`

Pay attention to the walkthrough command, the format is which is shown below:

`walkthrough editor-open-file path/to/somefile "Label Text"`

All you need to do is provide the entire path to the file that you want to open in the editor, in our case the index.js file. And give a text label that will be rendered in the Tutorial Step. If the user clicks on it, the editor will open up with the file as shown below in the left pane.

This makes it easy for the user to focus on the tutorial and not get distracted with navigating to some folder, etc. The experience comes into play again.

There are other custom elements supported too like Spotlight, indicating a Cloud Shell icon, etc. Please refer to the documentation. These are valuable elements to support a great experience for the reader.

Publishing and Launching the Tutorial

There are multiple ways to launching the tutorial, but I prefer the following:

1. I first publish the entire source code for the tutorial as a repository on Github. For e.g. here is the Github repository for the tutorial that I created: github.com/rominirani/Google-Cloud-Shell-Tutorial-Creation
2. In this repository, you will notice that I placed the tutorial.md file that contains our tutorial markdown code as explained above in the root folder.
3. In the README.md file, you need to add a Launch in Google Cloud Shell button as shown below:

4. You can add the button as follows:

[](https://console.cloud.google.com/cloudshell/open?git_repo=YOUR_REPO_URL&tutorial=YOUR TUTORIAL FILE NAME)

You just need to provide two variables:

• git_repo : The full Git repo URL
• tutorial : The tutorial file name. For e.g. tutorial.md

The tutorial parameter is a hint to the Cloud Shell that once it has setup the repository, it needs to start the tutorial present at tutorial.md. This will then open up the first step of the tutorial in the right pane.

A few observations

1. If you have been using Google Cloud Platform, you would have come across Google Codelabs. I do not think that this is a replacement for that but it can definitely ease the process of setting up a Cloud Shell environment with the files setup for you.

If you have never seen Google Codelabs, please do so. There are tons of tutorials to get your familiar with various GCP services. Do it now!

2. The folder structure that you see in my github repo is not the one to be strictly followed. You can organize your folders as you see fit. Just make sure that you provide the correct path when using custom elements to open the file in the editor and also for referencing your tutorial markdown file. I struggled a bit with that.

3. If you see the official documentation, you are asked to just use ``` … ``` for the code block. But I found that unless I use ```bash … ```, it did not render as expected.

4. There are a few hidden walkthrough commands like walkthrough conclusion-trophy which are not documented. It presents a nice trophy to you when you complete the stuff.

5. The experience and capabilities of the tutorials are centered around Cloud Shell. So your imagination is limited by what you can do with the Cloud shell. For e.g. I wanted to even lead the user to Cloud Console and automate some screens over there, but I believe I am crossing the line here.

6. You will notice that there are buttons to sending feedback for the tutorial. This includes a rating for your tutorial and a description by the user in case there are issues. I am not sure where the feedback is sent.

That brings this tutorial about creating tutorials to an end. Enjoy creating your tutorials for Cloud Shell !

Let a thousand tutorials bloom.

References

• Official Documentation : Tutorials in Cloud Shell.
• Google Cloud Platform Blog Announcement : Cloud Shell Tutorials: Learning experiences integrated into the Cloud Console.