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 Walkthrough 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 Walkthrough 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 Walkthrough with 'Cancel Tutorial' and can later resume from where they left off.
  • Code to-go: You can include code snippets in your Walkthrough. 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 Walkthrough launched

Console session with Walkthrough 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: Walkthroughs 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 Walkthrough, establish a well-defined goal you want your users to accomplish. Craft your Walkthrough keeping this goal in mind.
Original Revised Improvement
On the next page, you'll learn how to create a new Walkthrough. Continue on to the next step to start setting up your Walkthrough. 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 Walkthrough. It'll also walk you through generating a button that users can use to launch your finished Walkthrough.

Clear roadmap of lessons covered in the Walkthrough

Make sure to keep this focus when writing content!

Best Practices

  • Keep it short: The unique space constraints of the Walkthrough 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 Walkthrough off with an introduction.

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

    ## Let's get started!

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

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

    **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 Walkthrough, 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 Walkthrough.

  • 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 Walkthrough.
    Example

    ## In-context Walkthroughs

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

    The content is shown along with the Cloud Shell environment where you can carry out the Walkthrough steps. Having the Walkthrough 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 Walkthrough.

  • Walkthrough 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 Walkthrough 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 Walkthrough, use [Markdown](https://en.wikipedia.org/wiki/Markdown) and follow these guidelines:

    ### Edit the title

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

    ```

    # Teach me to write a Walkthrough

    ```

    ### 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 Walkthrough 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 Walkthrough.
    • Wrap up: Summarize important lessons that you'd like users to take away from the Walkthrough.
    • What's next: Help users along their journey by providing next steps - these might be recommended reading, supplementary resources, or even, another Walkthrough.
    • Look out for your users: Advise them to clean up any test resources they created for the purposes of the Walkthrough to avoid unwanted billing charges.
    Example

    ## Congratulations

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

    You're all set!

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

    For a complete list of Cloud Shell Walkthrough writing tools, refer to the [Walkthrough Markdown Reference](https://cloud.google.com/shell/docs/walkthrough-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>`.