教程内容类型

当有人对产品有基本了解并希望扩展其理解以解决特定问题时，教程很有用

在这篇文章中

教程通过引导用户完成整个工作流程以完成任务，帮助人们了解产品并解决现实世界中的问题。教程的语气比其他内容更具对话性。教程感觉像是开发者之间的对话，同时对具有不同技术知识的读者保持可访问性。具有教程的产品必须已经有一个快速入门。对于小巧的工作流程，请使用快速入门模型。

教程适用于希望获得专家建议以及与其问题相关的最佳实践的详细讨论的人。教程还可以帮助过去使用其他产品实施类似解决方案的人使用 GitHub。教程还可以帮助人们验证解决方案是否适合他们的需求。

在整个网站中，我们将教程和快速入门统称为“指南”。在 `/guides` 的着陆页上，我们会在指南列表中包含教程、快速入门和某些程序性文章，以供文档集使用。

如何编写教程

有关教程模板，请参阅 "模板”。

教程内容

  • 引言
    • 明确目标受众。
    • 清楚地说明所需的先决条件和先验知识。
    • 说明用户将完成或构建的内容。
    • 包含一个成功项目的示例。
    • 不包含完成任务所需的大致时间 - 这取决于完成教程的人员的经验水平。
  • 程序性部分
    • 根据教程的目标受众，步骤可以比程序性内容中使用的步骤更不显式和更正式。如果目标受众不需要那么详细的步骤，则无需使用现有的可重用内容来构建这些步骤。
      • 使用：“从您的个人资料中，点击 **设置**，然后点击 **开发者设置**。”
      • 避免：“在任何页面右上角，点击您的个人资料照片，然后点击 **设置**。在左侧边栏中，点击 **开发者设置**。”
    • 链接到其他文章或资源，而不是复制它们，以避免中断教程中的信息流。
    • 提供视觉提示。大量使用代码块和屏幕截图，帮助用户确信他们正在执行正确的操作。
    • 提供真实示例。
      • 例如，不要告诉用户“输入提交信息” - 相反，请提供一个与之前步骤匹配的适当示例提交信息。
  • 故障排除
    • 承认任务中可能出现的问题，并列出读者可能会遇到的几个常见问题及其解决方案。
  • 结论
    • 回顾已完成或构建的内容。参考引言中提供的项目作为成功项目的示例。
  • 下一步
    • 包含 2-3 个用户在完成教程后可以采取的实际操作步骤。链接到其他相关信息，例如
      • GitHub 上展示介绍概念的项目
      • docs.github.com 上的相关信息
      • 相关的 GitHub 技能
      • Hubber 发布的相关演讲、博客文章或社区论坛系列文章

教程标题指南

  • 遵循操作文章的标题指南。
  • 不要在标题中使用“教程”或“指南”。

教程示例

教程

语言和框架指南