{"id":532,"date":"2023-12-25T10:16:25","date_gmt":"2023-12-25T10:16:25","guid":{"rendered":"https:\/\/vmlogger.com\/algorithms\/?p=532"},"modified":"2023-12-25T10:16:25","modified_gmt":"2023-12-25T10:16:25","slug":"how-to-create-an-interactive-walkthrough-tutorial-in-cloudshell","status":"publish","type":"post","link":"https:\/\/vmlogger.com\/algorithms\/2023\/12\/25\/how-to-create-an-interactive-walkthrough-tutorial-in-cloudshell\/","title":{"rendered":"How to create an \u201cInteractive walkthrough\u201d tutorial in Cloudshell"},"content":{"rendered":"

While working on a Google open-source \u2014\u00a0Data Quality Monitor<\/a>, I was introduced to Google\u2019s\u00a0interactive walkthrough by one of my colleagues\u00a0<\/em><\/strong>Niels Overwijn<\/a>\u00a0while I was creating a step-by-step tutorial in Github\u2019s\u00a0Readme.md<\/em>\u00a0file for deploying the application in Google Cloud.<\/p>\n

It immediately caught my attention as\u00a0it is so simple yet powerful tool<\/em><\/strong>. Just by exploring its simple documentation by Google Cloud, I could start creating one for my project.<\/p>\n

In the Data Quality Monitor repository, if you look in the readme file, there is a cloud shell button, clicking on which you will be automatically taken to your Google Cloud account, your cloud shell will be instantiated and the repository will be cloned in the workspace and interactive tutorial will be launched as shown in the below picture.<\/p>\n

\n
\n
\"\"<\/picture><\/div>\n<\/div>\n<\/figure>\n

I figured, \u201cWhy not share this gem with all of you?\u201d So, without further ado, let\u2019s dive into what an interactive walkthrough in CloudShell is all about.<\/p>\n

What is an interactive walkthrough in Cloud Shell?<\/h1>\n

An interactive walkthrough in Cloud Shell is a step-by-step guide to using Cloud Shell and Google Cloud products to complete a specific task.\u00a0Walkthroughs are written in Markdown<\/em><\/strong>\u00a0and can include text, code, images, and videos. Users can run commands directly from the walkthrough to follow along and perform or learn any action that the provider wants them to perform.<\/p>\n

Why create an interactive walkthrough for your GitHub repository?<\/h1>\n

There are several benefits to creating an interactive walkthrough for your GitHub repository:<\/p>\n

    \n
  1. Reduce the installation\/learning curve:<\/strong>\u00a0Interactive walkthroughs can help users get started with your project quickly and easily. By providing step-by-step instructions, you can help users learn how to use your project\u2019s features and avoid common pitfalls.<\/li>\n
  2. Increase engagement:\u00a0<\/strong>Interactive walkthroughs are more engaging than traditional documentation. By allowing users to interact with the environment and see the results of their actions, you can help them learn more effectively.<\/li>\n
  3. Improve your project\u2019s documentation:\u00a0<\/strong>Interactive walkthroughs can be a valuable addition to your project\u2019s documentation. They can help you explain complex concepts clearly and concisely, and they can also provide users with hands-on experience.<\/li>\n<\/ol>\n

    How to create an interactive walkthrough for your GitHub repository<\/h1>\n

    To create an interactive walkthrough for your GitHub repository, follow these guidelines:<\/p>\n

      \n
    1. Create a new Markdown file in your repository.<\/li>\n
    2. In the Markdown file, you can add HTML as well as Google Cloud-provided markdown styles, walkthrough directives, etc. Walkthrough directives are HTML-like pre-defined tags that are used to create certain UI elements or perform certain actions in the Google Cloud shell window.<\/li>\n<\/ol>\n

      A few important directives examples:<\/strong><\/h1>\n

      1. Open file walkthrough directive:<\/h2>\n

      For example:<\/em><\/strong>\u00a0if you have a config.json file in your repository and you want the user to open that file and modify it accordingly. Then you can use the\u00a0Open file directive<\/em><\/strong>\u00a0to create a link in the tutorial to open that particular config file in editable format in the cloud shell window.<\/p>\n

      Click to open the config file to edit \r\n<walkthrough-editor-open-file<\/span> filePath<\/span>=\"FILE_PATH\"<\/span>><\/span>Open File<\/walkthrough-editor-open-file<\/span>><\/span><\/span><\/pre>\n
      The above markdown displays like below:<\/p>\n
      \n
      \"\"<\/picture><\/div>\n<\/figure>\n
      2. To create or select an existing project:<\/h2>\n
      To create a section or widget for the user to be able to select an existing project or create a new one, you can use the create project directive.<\/p>\n
      <h2<\/span> id<\/span>=\"set-up-a-project\"<\/span> data-text<\/span>=\"Set up a project\"<\/span>><\/span>Set up a project<\/h2<\/span>><\/span>\r\n<ol<\/span>><\/span>\r\n   <li<\/span>><\/span>\r\n      <walkthrough-project-setup<\/span> billing<\/span>><\/span><\/walkthrough-project-setup<\/span>><\/span>\r\n   <\/li<\/span>><\/span>\r\n<\/ol<\/span>><\/span>\r\n\r\n`Note:` In order to be able to install DQM successfully, you need to have billing enabled for your project.<\/span><\/pre>\n
      The above markdown code will turn into the following widget on your interactive tutorial page:<\/p>\n
      \n
      \n
      \"\"<\/picture><\/div>\n<\/div>\n<\/figure>\n
      3. To get the selected project ID or project name:<\/h2>\n
      In your tutorial, if you want to get the selected project name or ID, you can use one of the following directives i.e.<\/p>\n
      <p<\/span>><\/span><strong<\/span>><\/span>Project Name:<\/strong<\/span>><\/span> <walkthrough-project-name<\/span>\/><\/span>\r\n<strong<\/span>><\/span>Project ID:<\/strong<\/span>><\/span> <walkthrough-project-id<\/span>\/><\/span><\/p<\/span>><\/span><\/span><\/pre>\n
      After running the above directive, you can see your selected project ID and project name.<\/p>\n
      \n
      \"\"<\/picture><\/div>\n<\/figure>\n
      3. Conclusion Trophy:<\/h2>\n
      At the end of the tutorial, if everything is successful, you want to give a trophy to the user :); you can use the conclusion trophy directive as shown below code:<\/p>\n
      <h2<\/span>><\/span>Congratulations<\/h2<\/span>><\/span>\r\n<p<\/span>><\/span>\r\n   <walkthrough-conclusion-trophy<\/span>><\/span><\/walkthrough-conclusion-trophy<\/span>><\/span>\r\n<\/p<\/span>><\/span>\r\n<p<\/span>><\/span>You\u2019re all set!<\/p<\/span>><\/span><\/span><\/pre>\n
      The above code will look something like this as shown in the below picture:<\/p>\n
      \n
      \"\"<\/picture><\/div>\n<\/figure>\n
      \n
      To know all available directives and how to use them, you can refer to Google Cloud documentation here:\u00a0https:\/\/cloud.google.com\/shell\/docs\/cloud-shell-tutorials\/directives-cloud-shell-editor<\/a><\/p>\n<\/blockquote>\n
      Markdown Extensions:<\/h1>\n
      Cloud Shell tutorials support Markdown extensions to expand the capability of the Markdown language itself. To create a code block formatting you can use one of the extensions as shown in the below example:<\/p>\n
      If you want to run a shell script in cloud shell:<\/p>\n
      ```sh\r\n     gcloud config set project <walkthrough-project-name\/>\r\n```<\/span><\/span><\/pre>\n
      In the above example, I have used extended markdown to write a shell script that can be run in a cloud shell. I have also used one of the directives to get the selected project name.<\/p>\n
      The above markdown code will look something like shown in the below picture where the entire command can be either copied by clicking on the copy button in the top right corner or can be directly copy-pasted to the terminal. All you need to do is \u201cpress\u201d enter to execute.<\/p>\n
      \n
      \n
      \"\"<\/picture><\/div>\n<\/div>\n<\/figure>\n
      Refer to this Google documentation page for more extended features:\u00a0https:\/\/cloud.google.com\/shell\/docs\/cloud-shell-tutorials\/markdown-extensions<\/a><\/p>\n
      How to launch an interactive tutorial:<\/h1>\n
      To use an interactive walkthrough in Cloud Shell, follow these steps:<\/p>\n