教程风格指南

为了让用户有效地熟悉您的项目,本文介绍了一些准则,旨在帮助您以教程的形式最好地呈现您的内容。

Cloud Shell 特性

  • 独特的布局:教程显示在 Google Cloud Console 右侧的侧边栏中。
  • 导航:用户可以使用每个步骤中的下一步上一步按钮来浏览教程。还可以关闭教程,并从上次中断的地方继续。
  • 快捷使用代码:代码段可直接复制到 Cloud Shell 中。

已启动教程的控制台会话

一个打开教程窗格的 Google Cloud Shell Editor 会话。用户可以通过点击按钮将代码直接复制到 Google Cloud Shell 中,并通过下一步上一步按钮在页面之间移动。

写作风格

  • 保持轻松的风格:教程的行文风格应该是提供信息和帮助,而不应过于正式。
  • “您”、“用户”:使用第二人称代词(使用:“您”、“您的”;不要使用:“我们”、“我”、“我们的”等)。
  • 说明原因和结果:当要求用户执行某一步骤时,请说明操作背后的原因以及预期结果。
  • 具有清晰的目标:在编写教程的内容之前,先确定一个您希望用户达成的明确目标。在制作教程的过程中,请牢记这一目标。
原始 修订版 改进
在下一页中,您将学习如何创建新教程。 继续执行下一个步骤,以开始设置您的教程。 以用户为中心;使用主动语态

使用轻松的语言

运行此命令:

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

要显示所有项目及其 ID 号的表格式列表(标题为“Projects”),请运行以下命令:gcloud projects list --format="table[box,title=Projects](name, projectId)" 提前说明原因,以便用户可以了解预期结果
Let's get started! Let's get started!

本指南将为介绍如何构建您自己的互动式教程,另外还将介绍如何生成一个按钮,供用户用来启动您最终完成的教程。

明确地勾勒出教程中包含的知识要点

在编写内容时,请务必重点突出这些知识要点!

最佳做法

  • 保持简短:教程窗格的独特空间限制意味着,一次只能向用户呈现有限的信息。应避免出现难以浏览且需要垂直滚动的大段文本;最好以简短的段落来呈现信息。

    • 尽量让每页不超过 5 个步骤和 3 个代码段。

    • 每个段落最好不要超过 5 行内容,并且一个段落最好仅涉及一个概念。

    • 如果某个页面必须很长,请尽量使其不要超过窗格长度的两倍。

    • 代码和终端信息块应足够简短,以方便人查看:

      • 尽量不要超过 10 行。
      • 每行尽量不要超过 80 个字符,以减少水平滚动幅度。
      • 避免使用多命令代码块,以免用户不得不批量执行复制-执行操作。
  • 简介页面:以简介内容作为教程的开头部分。

    • 设定预期:简要说明用户在完成本教程后会有何收获。
    • 估算所需时间:粗略估算用户学完教程需要花费多长时间。尽量制作一个可在 15 分钟内学完的教程。如果您的教程篇幅较长(或者包含 15 个以上内容密集的页面),请考虑将其分解成几个篇幅较短的教程。
    • 提前准备:明确说明用户可能需要提前设置的所有必要资源或访问权限,以便其能够顺畅地学习教程。
    示例

    ## 让我们开始吧!

    通过提供互动式教程,您可以帮助用户快速开始使用您的项目。

    本指南将为您介绍如何构建您自己的互动式教程(类似于本教程),另外还将介绍如何生成一个按钮,供用户用来启动您最终完成的教程。

    **完成学习所需的时间**:大约 10 分钟

    **前提条件**:一个 Cloud Billing 帐号

    点击**继续**按钮,以转到下一步。

  • 背景信息页面

    • 设置场景:在编写教程时,提供相关背景信息通常很有帮助。这可能意味着提供简短的产品概述,或者简要介绍某个界面的重要功能。
    示例

    ## 什么是 Cloud Shell?

    在您开始之前,我们先简要回顾一下 Cloud Shell 有哪些功能。

    Cloud Shell 是一种托管式个人虚拟机,它预装了适用于 Google Cloud 产品的开发者工具。此交互式 Shell 环境带有内置的代码编辑器、永久性磁盘存储空间和网页预览功能。如需通过命令行访问,请参阅 [console.cloud.google.com/cloudshell] (https://console.cloud.google.com/cloudshell)。

    您可以将用户引至 Cloud Shell,以帮助他们快速开始使用您的项目;让他们可以逐步熟悉某种使用场景,并熟悉项目的功能。

    继续执行下一个步骤,以开始设置您的教程。

  • 基本示例:

    • Hello World:您提供的第一个示例应当简单明了,以便用户无需查看太多说明即可亲自试验。该示例的简易程度应该与您的 Hello World 示例相当。然后,您可以将此示例作为基础,来构建教程中的其他示例,从而以举例的方式阐释相关概念。
    示例

    ## 环境内嵌教程

    您现在看到的是一个环境内嵌教程。

    教程内容的旁边显示了 Cloud Shell 环境,您可以在该环境中执行教程中的步骤。通过在同一个地方打开教程和开发环境,您的用户可以获享直观的单幕体验,从而能够更加轻松地开始使用您的项目。

    现在,请尝试运行以下命令:

    ```bash

    echo "Hello Cloud Shell"

    ```

    **提示**:点击代码框旁边的复制按钮,然后将复制的命令粘贴到 Cloud Shell 终端,以运行该命令。

    接下来,您将编写并发布一个简单的教程。

  • 教程内容

    • 谨慎使用格式:带有格式(粗体、斜体等)的文本会分散读者的注意力;请仅在必要或有益时(例如,用于警告、学习要点等内容)使用带有格式的文本。
    • 一致的语法:在描述用户操作时使用祈使句,并确保在句末加上句号。
    • 引用链接:如果有必要提供相关背景信息,则可以添加补充性链接([链接文本](链接网址)),以供用户参阅。
    • 使用聚焦功能,而非屏幕截图:聚焦功能可以突出显示界面元素在 Console 中的位置,从而能够帮助用户轻松找到相关元素,而无需参照图片费力查找。
    • 备用视图:如果可能,请提供以静态形式呈现的教程内容的链接,以便用户可以自由选择通过哪种视图来查看所提供的信息。
    • 建议添加提示:在适用的情况下,请添加提示(以“**提示:**”这种形式突出显示),以便为用户提供更直观的解决方案和最佳做法。
    示例

    ## 使用 Markdown 编写内容

    编写教程时,请使用 [Markdown] (https://en.wikipedia.org/wiki/Markdown),并遵循以下准则:

    ### 修改标题

    修改本教程的标题(“# 有关如何在 Cloud Shell 中编写教程的简介”),将其更改为:

    ```

    # 教我如何编写教程

    ```

    ### 添加新步骤

    接下来,在标题后面添加一个步骤,如下所示:

    ```

    ## 第 1 步

    这是我刚刚添加的新步骤。

    ```

    一个页面显示教程的一个“步骤”。

    **提示**:要浏览各个步骤,用户需要使用“后退”和“继续/前进”按钮。

  • 摘要

    • 恭喜:请务必添加奖杯图标 (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>),以感谢用户花时间学完教程。
    • 概括:总结您希望用户通过该教程学到的知识要点。
    • 后续步骤:为用户提供后续步骤,帮助他们继续自己的学习之旅。这类内容可能是推荐的阅读资料、补充性资源,甚至是其他教程。
    • 提醒用户注意:建议用户清理为学习教程而创建的所有测试资源,以避免产生不必要的结算费用。
    示例

    ## 恭喜!

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

    大功告成!

    现在,您可以让用户在 Cloud Shell 中启动您的教程并轻松地开始使用您的项目。

    如需查看 Cloud Shell 教程编写工具的完整列表,请参阅 [教程 Markdown 参考] (https://cloud.google.com/shell/docs/tutorial-markdown-reference)。

    **不要忘记最后的清理工作**:如果您创建了测试项目,请务必删除这些项目,以避免产生不必要的费用。请使用“gcloud projects delete <PROJECT-ID>”命令。