编写 Codelab

简介

Codelab 是用 Markdown 语法编写的互动教程。我们会在 blocklycodelabs.dev 上发布 Codelab。Codelab 会混合使用自然语言、代码示例和屏幕截图，以打造更具吸引力的教程体验。Codelab 的目标用户会一边阅读一边运行代码。

编写 Codelab 是为社区做出贡献的绝佳方式。这样，您就可以分享自己的知识，并帮助下一位遇到相同问题的开发者更轻松地解决问题。

优秀的 Codelab 有何特点？

优质的 Codelab 重点突出且易于阅读。它清楚地告诉用户他们将构建什么以及将学习什么，并引导用户编写和理解代码以完成特定任务。

流程

如果您有 Codelab 方面的想法，可以在 blockly-samples 代码库中提交功能请求，告诉我们您的想法。说明您想在 Codelab 中教授的内容以及要构建的内容。我们将讨论并完善这个想法。 然后，您可以撰写相关文档，并为其提交拉取请求。经过审核后，Blockly 团队的成员会发布该文档。

书写提示

本页面的其余部分包含一系列提示和问题，可引导您完成 Codelab 的撰写。

如需快速了解技术写作，请参阅技术写作第一课。

受众群体

  • 目标读者是谁？
  • 他们对使用 Blockly 的了解程度如何？
  • 他们想学习什么？

设置

  • 用户运行您的代码所需的最低设置是什么？

如有帮助，您可以在 examples 目录中发布起始代码和完整代码。

结构

与任何写作一样，先从大纲开始。以下是适用于大多数 Codelab 的良好结构：

  • 简介
    • 学习内容
    • 构建内容
    • 须知事项
    • 设置说明
  • 第 1 步：[在此处添加标题]
    • 说明/动机
    • 代码示例
    • 预期结果
    • （可选）更多说明
  • …
  • 第 10 步：[在此处输入标题]
  • 总结
    • 要点回顾
    • 您构建的内容
    • 其他资源
    • 指向已完成代码的链接（如果有）

虽然您可以包含十个以上的步骤，但如果步骤数量达到二十个，您应该考虑将其拆分为两个 Codelab。

写作风格

  • 使用对话式写作风格。
  • 使用标题让内容条理分明。
  • 使用项目符号列表来分隔大段文字。
  • 使用图片和 GIF！

代码样式

  • 您可以使用 ES5、ES6 或 TypeScript 进行编写，但需要在开头告知读者您使用的是哪种语言。
  • 遵循 Google 样式指南