教程主题

教程的目的是向读者展示如何在安全环境中“边做边学”。教程应能让读者快速获得成功感。教程的长度可以从几个步骤到多个子任务不等。

如果您有想要开发的教程想法，请联系 Grafana Labs 文档团队。内部贡献者可以在 Slack 上联系我们，外部贡献者可以发送电子邮件至 docs@grafana.com 或在 Grafana Labs 社区 Slack 的 #docs 频道联系我们。

教程结构

教程主题包含以下要素

主题标题： 撰写结合动词和宾语的教程主题标题。
概述： 让用户了解完成本教程将实现的目标。提供背景信息并包含用户将要完成的任务列表。建议文本：“在本教程中，您将……”。
本教程主题的此部分可以包含概念性材料。但是，请将概念性信息限制在与当前目标相关的范围内。
如果您发现自己在写一个冗长的引言，可以考虑创建一个概念主题，然后在教程引言中写该概念的简化版本。您可以从教程中链接到概念主题。
开始之前（可选）： 描述读者在教程开始前应完成的任务或提供相关链接。链接有时可能与产品无关，例如“准备好这个东西”。
此外，此部分还可以包含用户在开始教程之前应做出的决定或需要确认的权限。如果有多于一个先决条件，请使用无序列表。
如果没有先决条件，请勿包含此部分。
任务部分（或多个部分）：为完成教程所需的每个任务创建一个部分。按照任务指南撰写任务。
要确定您的教程应包含哪些任务和步骤，请进行目标分析并确定用户想要实现的有价值的结果。将教程限制在满足该目标所需的任务范围内。与主题专家 (SME) 合作确定目标和最少的任务集。如果可能，记录 SME 完成实现目标所需的任务，或者如果更方便，请 SME 录制任务演示。
与主题专家 (SME) 合作，以便
- 提供解释如何访问或设置完成任务所需数据的步骤。有关更多信息，请参阅教程数据。
- 不要在标题中包含书面的步骤编号，例如“步骤 1：摘苹果。”。而是只包含动词和宾语，例如“摘苹果。”
- 只包含通往教程目标的直接路径所需的任务，而不是可选或替代路径。
- 尽量减少任务步骤中的解释。相反，链接到相关概念、任务和参考主题中的支持性解释。
总结（可选）： 描述教程用户已完成的内容。
后续步骤（可选）： 如果存在，提供合乎逻辑的后续步骤。

Annotated example of a tutorial page's structure

撰写教程主题

要撰写教程，请完成以下步骤

如果您的项目仓库中尚不存在 docs/sources/tutorials 目录，请添加该目录。
该教程与您仓库中的其他文档一起提交，发布后将显示在 Grafana 教程页面上。有关更多信息，请参阅发布您的教程。
在 tutorials 目录中创建一个遵循以下命名约定的子目录
- 目录名称应包含一个动词和一个宾语。
- 使用小写字母。
- 在单词之间添加连字符。
在教程目录中创建一个 index.md 文件。
将内容添加到教程模板的副本中。
向 index.md 文件添加前言。
有关前言的更多信息，请参阅前言。

教程模板

准备好撰写时，复制教程模板并添加您的内容。

教程与任务主题的区别

教程与任务主题的区别在于，教程用于学习，而任务用于实际操作工作。另一个重要区别是，教程通常提供一个“沙箱”环境——用户可以安全地进行实验的数据源。

教程数据

根据应用程序的不同，您的教程数据可能位于

沙箱中
测试服务器上
用户在本地克隆的演示仓库中

例如，“体验 Grafana Mimir”教程提供了一个仓库，用户可以克隆该仓库来完成教程。相比之下，“在 Grafana Mimir 中存储 Exemplar”主题是一个纯粹的任务，用户将遵循该任务来完成其工作。有关撰写任务的指导，请参阅任务。

如果访问教程数据很复杂，请将说明包含在教程的步骤中。如果访问数据很简单，请将其包含在“开始之前”部分。

发布您的教程

您将教程源文件存储在项目仓库的 docs/sources/tutorials 目录中，并挂载到教程仓库，以便它显示在教程页面上。您将源文件存储在项目仓库中，供团队成员评审和编辑内容。

以下部分描述了如何从项目目录中隐藏教程并将其显示在教程页面上。

从目录中隐藏您的教程

教程用于学习，因此最好将它们集中显示在教程页面上，可以直接从 Grafana 网站的学习菜单访问。因此，您需要隐藏教程，使其不会出现在项目目录中。

开始之前

在完成这些步骤之前，您需要在 docs/sources 下创建一个 tutorials 目录，并按照撰写教程主题部分所述将您的教程添加到其自己的子目录中。

从文档目录中隐藏您的教程

打开您项目的 docs/sources/_index.md 文件。
将以下 YAML 添加到页面的前言中，将 <PROJECT> 替换为您项目的 URL 路径。
如果 cascade 前言已存在，您必须将此片段与现有前言合并。
注意
Hugo cascade 前言有两种形式：array 和 mapping。
以下片段使用了 cascade 前言的 array 形式。如果您的前言尚未采用 array 形式，则需要将其更改为该形式。
有关更多信息，请参阅 cascade 前言文档
yaml
```
cascade:
  - _target:
      path: /docs/<PROJECT>/*/tutorials/**
    _build:
      list: false
      render: false
```

将您的教程添加到教程页面

注意
此过程适用于具有更新 Grafana 网站仓库权限的撰写者。

将您的教程添加到教程页面

将以下 YAML 添加到网站仓库中 config/_default/config.yaml 文件中的 manual_mounts 字段。
将 <PROJECT> 替换为您的项目名称，将 <TUTORIAL> 替换为您的教程目录，并将 <VERSION> 替换为您要挂载的文档版本。通常 <VERSION> 是“next”或“latest”之一。
yaml
```
- source: content/docs/<PROJECT>/<VERSION>/tutorials/<TUTORIAL>
  target: content/tutorials/k8s-monitoring-app
```
将以下 YAML 添加到网站仓库中 data/tutorials.yaml 文件中的 list 字段。
将 <TUTORIAL> 替换为您的教程目录，并将 <LEVEL> 替换为“beginner”、“intermediate”或“advanced”之一，具体取决于您的教程难度。
yaml
```
- page: /tutorials/<TUTORIAL>
  level: <LEVEL>
  type: tutorial
```

教程主题示例

请参考以下教程示例

此页面有帮助吗？

在 GitHub 中建议编辑

创建 GitHub 问题

发送邮件至 docs@grafana.com

帮助和支持

社区