Walkthrough Writing Guide

In order for users to effectively familiarize themselves with your project, here are a few guidelines to help best present your content in tutorial form.

Cloud Shell Features

  • Unique layout: Walkthroughs are presented in a side panel (310 pixels in width) on the right hand side of Google Cloud Console.
  • Navigation: Users can move through the tutorial using the 'Continue' and 'Back' buttons. Note, to progress through a revisited step, the button is 'Forward' (instead of 'Continue'). Users also have the choice of quitting the tutorial with 'Cancel Tutorial' and can later resume from where they left off.
  • Code to-go: You can include code snippets in your tutorial. They'll be code formatted with this inline icon, Copy Icon, to allow users to paste these snippets into Cloud Shell directly.

Console session with tutorial launched

Console session with tutorial pane open on the right hand side. Users can copy code directly into Cloud Shell using the inline icon and can move between pages using 'Back' and 'Continue'.

Writing Style

  • Keep it light: Tutorials should be informative and helpful in tone but not overly formal.
  • You, the user: Use second person pronouns (do use: you, your; don't use: we, I, our, etc.)
  • Explain cause and effect: When asking users to carry out a step, explain the reasoning behind the action and the expected result.
  • Have focused goals: Before writing the content for your tutorial, establish a well-defined goal you want your users to accomplish. Craft your tutorial keeping this goal in mind.
Original Revised Improvement
On the next page, you'll learn how to create a new tutorial. Continue on to the next step to start setting up your tutorial. Focus on the user; use of active voice

Use of relaxed language

Run this command:

``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ```

To display a tabulated list of all your projects and their ID numbers, titled 'Projects', run the following command: ``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` Explanation of reasoning upfront to set expectations about the output
Let's get started! Let's get started!

This guide will show you how to build your own interactive tutorial. It'll also walk you through generating a button that users can use to launch your finished tutorial.

Clear roadmap of lessons covered in the tutorial

Make sure to keep this focus when writing content!

Best Practices

  • Keep it short: The unique space constraints of the tutorial pane mean that a limited amount of information can be presented to a user at a time. Avoid large chunks of text that are difficult to scan and require vertical scrolling; favor information presented in bite-sized chunks.

    • Aim for no more than 5 steps and 3 code snippets per page.

    • Paragraphs should ideally be 5 lines or less, and should deal with a singular concept.

    • If a page must be long, aim to have it be a maximum of twice the length of the pane.

    • Code and terminal blocks should be small enough to read:

      • Aim for 10 lines or less.
      • Aim for 80 characters or less per line, to reduce horizontal scrolling.
      • Avoid multi-command code blocks to prevent users from having to do a bulk copy-execute.
  • Introductory page: Start your tutorial off with an introduction.

    • Set expectations: Briefly explain how your users will profit from completing this tutorial.
    • Estimated time commitment: Roughly estimate how long users can expect to spend on the tutorial. Aim to create a tutorial that can be finished under 15 minutes. If your tutorial is longer (or consists of more than 15 densely worded pages), consider breaking it into a series of smaller tutorials.
    • Be upfront: Clearly state any prerequisite resources or access that users might need to have set up to work through the tutorial uninterrupted.
    Example

    ## Let's get started!

    Get your users up and running quickly with your project by including an interactive tutorial.

    This guide will show you how to build your own interactive tutorial (like this one). It'll also walk you through generating a button that users can use to launch your finished tutorial.

    **Time to complete**: About 10 minutes

    **Prerequisites**: A GCP account

    Click the **Continue** button to move to the next step.

  • Background page

    • Set the scene: It's often helpful, when writing a tutorial, to furnish it with context. This might mean providing a short overview of the product or quickly running through salient features of a UI.
    Example

    ## What is Cloud Shell?

    Before you get started, let's briefly go over what Cloud Shell can do.

    Cloud Shell is a personal hosted Virtual Machine which comes pre-loaded with developer tools for Google Cloud products. This interactive shell environment comes with a built-in code editor, persistent disk storage, and web preview functionality. To use command-line access alone, visit [console.cloud.google.com/cloudshell](https://console.cloud.google.com/cloudshell).

    You can direct your users to Cloud Shell to help them quickly get started with your project; giving them an opportunity to step through a use case and familiarize themselves with your project's functionality.

    Continue on to the next step to start setting up your tutorial.

  • Basic Examples:

    • Hello World: The first example you provide should be simple enough for your user to test without much explanation. It should be your Hello World equivalent. Use this example as a base to keep building on to exemplify concepts through the tutorial.
    Example

    ## In-context tutorials

    What you're looking at now is an in-context tutorial.

    The content is shown along with the Cloud Shell environment where you can carry out the tutorial steps. Having the tutorial and development environment open in the same place makes it easier for your users to start using your project through a straightforward single screen experience.

    Try running a command now:

    ```bash

    echo "Hello Cloud Shell"

    ```

    **Tip**: Click the copy button on the side of the code box to paste the command in the Cloud Shell terminal to run it.

    Next, you'll write and launch a basic tutorial.

  • Tutorial Content

    • Format with caution: Text formatting (bold, italics, etc.) is distracting; use it only when necessary and to your advantage (for warnings, key learnings, etc.).
    • Consistent grammar: Use imperative tense when describing user action and be sure to end sentences with a period.
    • Refer to links: Where essential for context, include supplementary links ([link text](link URL)) so that users can do their own research.
    • Choose spotlighting over screenshots: Spotlighting, an action that highlights where UI elements are in the Console, demonstrates position so that users can identify elements without searching an image.
    • Alternate view: If possible, provide a link to your tutorial content offered as static content; this gives users the freedom to pick how they'd like to consume the provided information.
    • Tips appreciated: Where applicable, add in tips (called out by "**Tip:**") to provide users with more intuitive solutions and best practices.
    Example

    ## Writing in Markdown

    To write your tutorial, use [Markdown](https://en.wikipedia.org/wiki/Markdown) and follow these guidelines:

    ### Edit the title

    Modify the title of this tutorial ('# Introduction to writing tutorials in Cloud Shell') by changing it to:

    ```

    # Teach me to write a tutorial

    ```

    ### Add a new step

    Next, add a step just after the title like this:

    ```

    ## Step 1

    This is a new step I've just added.

    ```

    Each 'step' of a tutorial is displayed on one page.

    **Tip**: To move through steps, users will use the 'Back' and 'Continue/Forward' buttons.

  • Summary

    • Congratulations: Be sure to add in a trophy icon (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>) to appreciate users taking the time to finish the tutorial.
    • Wrap up: Summarize important lessons that you'd like users to take away from the tutorial.
    • What's next: Help users along their journey by providing next steps - these might be recommended reading, supplementary resources, or even, another tutorial.
    • Look out for your users: Advise them to clean up any test resources they created for the purposes of the tutorial to avoid unwanted billing charges.
    Example

    ## Congratulations

    <walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>

    You're all set!

    You can now have users launch your tutorial in Cloud Shell and have them start using your project with ease.

    For a complete list of Cloud Shell tutorial writing tools, refer to the [Tutorial Markdown Reference](https://cloud.google.com/shell/docs/tutorial-markdown-reference).

    **Don't forget to clean up after yourself**: If you created test projects, be sure to delete them to avoid unnecessary charges. Use `gcloud projects delete <PROJECT-ID>`.

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Shell