简介
Codelab 是一种用 Markdown 语法编写的交互式教程。我们的 Codelab 发布在 blocklycodelabs.dev 上。Codelab 会混合使用自然语言、代码示例和屏幕截图，打造更有趣的教程体验。Codelab 的目标用户会边看边运行代码。
编写 Codelab 是向社区贡献力量的绝佳方式。这样一来，您就可以分享自己的知识，并为下一位遇到相同问题的开发者提供帮助。
什么样的 Codelab 才算出色？
优质的 Codelab 应重点突出，且易于阅读。它会向用户明确说明他们将构建什么内容以及将学到什么知识，并引导用户编写和理解代码以完成特定任务。
流程
如果您有 Codelab 方面的想法，可以在 blockly-samples 代码库中提交功能请求，告诉我们您的想法。请说明您要教授的内容以及您将在 Codelab 中构建的内容。我们将讨论并优化该想法。 然后，您可以编写该更改并提交拉取请求。经过审核后，Blockly 团队成员会发布您的资源。
书写提示
本页面的其余部分包含一系列提示和问题，可引导您编写 Codelab。
如需快速了解技术写作，请参阅技术写作一课。
受众群体
- 目标读者是谁？
- 他们对使用 Blockly 已经了解了哪些内容？
- 他们在尝试学习什么？
设置
- 用户需要满足哪些最低设置要求才能运行您的代码？
如果有帮助，您可以在 examples 目录中发布起始代码和完成代码。
结构
与任何写作一样，先列出大纲。这对于大多数 Codelab 来说都是一个不错的结构：
- 简介
- 学习内容
- 构建内容
- 须知事项
- 设置说明
- 第 1 步：[此处填入标题]
- 说明/动机
- 代码示例
- 预期结果
- （可选）更多说明
- …
- 第 10 步：[Title goes here]
- 摘要
- 要点回顾
- 您构建的内容
- 其他资源
- 指向完成的代码的链接（如果有）
虽然您可以设置超过 10 个步骤，但如果超过 20 个步骤，则应考虑将其拆分为两个 Codelab。
写作风格
- 使用对话式写作风格。
- 使用标题来明确组织结构。
- 使用项目符号列表来分隔大量文本。
- 使用图片和 GIF 图片！
代码样式
- 您可以使用 ES5、ES6 或 TypeScript 编写，但需要在开头告知读者所用语言。
- 遵循 Google 样式指南