如何为DigitalOcean社区教程编写提案和大纲
介绍
所以你想为 DigitalOcean 写一个教程！ DigitalOcean 编辑团队在这里为像您这样的作家提供支持：希望与社区中的其他人分享知识的开发人员和工程师。
因为 DigitalOcean 不能接受提交给我们的每个教程，所以我们要求在批准您开始编写之前查看提案。 我们不希望你在知道自己是否被录取之前写完整个教程，所以我们要求提供详细的大纲。 这样，我们就可以很好地了解您想写的内容，并且可以在您开始写作之前为您提供一些反馈。 这是对文章进行结构更改的最佳时机，因为修改大纲比修改草稿要容易得多。 有了一个好的大纲，你就有了一个框架，可以让写作过程更加顺利。
在本文中，您将了解如何为您的教程构思制定提案和大纲。 您将首先做一些准备，以帮助您塑造内容，您将决定您希望读者实现的目标，然后您将定义使他们达到目标的步骤。 写作过程是迭代的，所以你可能会发现自己回到了前面的步骤，但这个框架将有助于创建大纲。
第 1 步——定义你的焦点
首先要决定的是你想写什么。 通常，您会从一个名词开始这个想法，例如：Nginx、Helm 或 React。 接下来，找到与名词相关的动词：您希望用户对产品做什么？ 或者换句话说，读者的学习成果是什么？ 在这个阶段，你将把注意力从作者转移到读者身上。 而不是“我想写什么？” 问题变成了“读者想要完成什么？” 找到正确的动词将回答这个问题。 像“学习”或“理解”这样的动词不是教程的好主题，因为它们没有可衡量的结果。 相反，请考虑以下动词：
- 安装
- 创造
- 配置
- 整合
- 部署
- 监视器
- 测试
- 安全的
- 自动化
- 疑难解答
几乎所有 DigitalOcean 教程都以“How To”开头，这让您可以引导您选择一个好的动词。 以下是使用带有适当动词的名词的优秀教程标题：
这可以让你清楚地说明读者的学习目标，这也应该有助于你定义你的标题。 这两个都是我们在您的提案中要求的信息。
一旦您正确定义了主题，您就可以将注意力转移到您正在为谁写作。
第 2 步 — 确定受众
计划教程时要考虑的下一件事是谁来阅读它。 谁将从本教程中受益最多，他们已经知道多少？ 他们已经知道多少将决定您需要提供多少背景信息，这会影响教程需要多长时间。
例如，教程 Initial Server Setup with Ubuntu 20.04 假设背景知识很少。 它解释了 root 是什么，以及 SSH 密钥是如何工作的。 这是第一次设置服务器的读者的合适受众。
教程 如何在 DigitalOcean Kubernetes 上使用 Flagger 逐步交付版本假设读者有更多的经验。 它假设读者熟悉 Kubernetes、Helm 和 Nginx，并且已经配置了一个使用所有这些技术的集群。 这允许作者跳过配置这些产品，而专注于作为教程主题的 Flagger。
注意： 必备教程在建议的教程进阶时很有用。 DigitalOcean 有一个包含 3,000 多个教程的库，其中任何一个都可以用作您提出的教程的先决条件。 Flagger 教程具有设置 Kubernetes、Helm 和 Nginx 等的先决条件。
对于 DigitalOcean 教程，狭窄的受众通常比广泛的受众更好。 如果您正在撰写有关如何配置 Kubernetes 负载平衡设置的文章，您可能认为受众应该包括所有使用 Kubernetes 的人，但如果您将受众集中在拥有足够集群和足够多的 Kubernetes 管理员上，那么您将获得一个更有用的教程流量需要微调负载均衡器。 换句话说，更高级的观众。
这并不意味着您的教程不会具有广泛的吸引力，您可以提供额外的上下文来吸引其他技能水平的读者。 但是，如果您缩小受众范围，计划阶段会更容易。
定义您的受众将使您了解需要涵盖多少内容，或者换句话说，范围。
第三步——确定范围
与观众一样，DigitalOcean 教程的范围应该很窄。 尝试将注意力集中在一项任务上。 关于“如何使用 React 前端和 MySQL 数据存储部署节点应用程序”的教程有很多组件和很多步骤。 我们宁愿看一个关于 如何部署 Node 应用程序 的教程。 第一个教程成功发布后，您可以使用第一个教程作为先决条件提出另一个教程，并以这种方式构建更复杂的解决方案。
狭窄的范围也是可取的，因为我们希望读者能够成功地重现这些步骤。 您可以编写一个涉及六个不同服务器的监控教程，但读者需要设置这么多 Droplet，这可能不方便或昂贵。 如果您只需两个 Droplet 就可以实现相同的目标，那么读者可以推断出更大的网络。
同样，尽量避免需要多种不同技术的教程。 关于（例如）“如何在 Debian 上使用 TravisCI 和 Grafana 监控部署 Flask 应用程序”的教程仅对使用所有这些确切技术的读者有用。 如果其中一种技术被替换或不再受支持，这会限制教程的生命周期。 本指南的例外是专门用于演示特定技术堆栈（例如 LAMP 或 Elastic）的使用的教程。
定义了教程的限制后，您可以开始为您的教程创建带有大纲的框架。
第 4 步 - 集思广益的任务
既然您知道要写什么以及为谁写，您就可以开始整理大纲了。 该过程的第一部分是集思广益，与您尝试解决的问题有关。 想想所涉及的整体任务，以及您可能采取的各个流程。 例如，如果您正在编写有关 如何在 Ubuntu 上安装 Nginx 的教程，您将包含 sudo apt install nginx 的步骤，但还有其他注意事项。 在本教程中，作者包含了以下附加步骤：
- 调整防火墙以允许访问
- 验证网络服务器
- 管理流程
- 设置服务器块
这些步骤严格来说不是 install nginx 过程的一部分，但它们对于正确安装 Nginx 是必需的，这就是教程增加基本文档价值的原因。 仔细考虑识别这些额外任务的过程，并在您想到它们时将它们写下来。 此时您不必将它们整理好。 您只是在定义要涵盖的内容。
这可能要花点时间。 例如，您可能不会考虑立即调整防火墙，因为您的防火墙通常配置正确。 当你想到它时，把它写下来。 在这一步要包容。 想想可能“很高兴”或不严格相关的任务。 一旦您想到了要包括的所有内容，就该组织起来了。
第 5 步 — 将任务组织成大纲
上一步为您提供了教程中可能包含的任务列表，因此下一部分是组织它们。 其中一些会很清楚，因为操作流程：您必须先运行 install nginx 命令才能测试结果，因此必须先执行安装步骤。 有些步骤可能不那么明显：读者应该在安装之后还是之前配置防火墙？ 根据读者的学习目标考虑每一步：这一步如何帮助他们朝着总体目标前进？ 有些步骤没有特定的地方需要发生，这很好。
确保流程的每一步都完成了一些有形的事情，这意味着每一步都应该有一个有用的动词。 如果您将“了解防火墙的工作原理”作为一个步骤编写，那并不能完成可证明的事情。 “配置防火墙”这一步给读者留下了一些具体的东西：一个阻止大部分流量但允许一些流量的防火墙。
您可能已经写下了本教程范围之外的一些步骤。 例如，您需要一个 Ubuntu 服务器才能在其上安装 Nginx，但这已在另一个教程中介绍，因此您不需要单独的步骤。 在这种情况下，您可以将“设置 Ubuntu 20.04 服务器”添加到先决条件列表中，以及指向现有教程的链接。 再次，记住您在第 1 步中定义的学习目标，并以此作为您判断这些步骤是否在范围内的指南。
其他步骤可能过于先进，不在范围之内。 您可能希望安装 Nginx 以将其用作反向代理，但该设置与安装是分开的，最好在单独的教程中进行介绍。 在我们的示例教程中，作者建议设置服务器块，但指出这是建议，而不是安装的必需部分。
通过添加有关每个步骤的一些细节来完成您的大纲。 用几句话准确地告诉我们读者会做什么，为什么每一步都很重要，以及它与下一步的关系。 对于防火墙步骤，您可以添加“读者将使用 ufw 的 Nginx HTTP 配置文件以仅允许端口 80 上的流量。 这是面向公众的 Web 服务器的标准配置。”
第 6 步——避免大纲陷阱
你的大纲有两个目的：它作为一个框架，使写作过程更容易，它会让 DigitalOcean 编辑团队知道你打算写什么，所以他们可以决定是否接受它进行出版。 以下是我们通常在大纲中看到的一些内容，我们建议避免这些内容以获得最佳接受机会：
- 背景步骤：如果您有一个步骤，读者没有做任何具体的事情，或者只是提供背景的步骤，请寻找其他地方来放置该信息。 如果您想提供一些技术常用的背景知识，可以在本教程的介绍部分。 如果您要解释读者为何采取措施，请考虑使用“及时”解释。 例如，不要先解释防火墙背后的理论，而是让读者使用命令来配置防火墙，然后准确解释他们使用这些特定命令的原因。 当读者亲身实践与理论联系起来时，他们会学得更好。
- 无法解释的步骤： DigitalOcean 的编辑在各种技术方面拥有丰富的经验，但我们并不是所有方面的专家。 为大纲中的每个步骤添加一些解释将有助于我们了解这些步骤如何组合在一起以实现您的目标。 像“设置用户”这样的步骤本身可能不清楚，但您可以添加“数据库服务需要具有特定权限的专用用户，以确保安全。 在这一步中，读者将创建该用户并设置权限。” 这样，我们就会知道为什么需要这一步。
- 克隆一个 repo： 许多大纲都有一个步骤 1，要求读者克隆一个 repo 以获得示例项目以在教程中部署。 我们避免这种模式有几个原因。 首先，我们需要确保 repo 在教程的整个生命周期内都可用。 （如果需要 repo，我们会将其克隆到 DigitalOcean 社区站点并在此处托管。）其次，出于安全原因，我们不会要求读者运行我们尚未完全解释的代码。 第三，我们将每个代码块都视为学习机会，即使它与教程主题没有直接关系。 如果您的项目包含的 CSS 文件过于复杂而无法在不分散本教程的情况下进行解释，请考虑简化 CSS。 将示例项目保持在教程所需的最低限度可以让您将焦点保持在它所属的位置。
- 步骤过长： 有时您的步骤中会包含其他从属任务。 例如，您可能有一个步骤需要在服务器上序列化信息，将其传输到客户端，然后在呈现之前对其进行反序列化。 如果您发现您的步骤将受益于副标题，这表明您应该将步骤分成两个或更多个更小的步骤。 您的编辑可以就这个问题提供建议。
结论
在本教程中，您已经完成了定义教程并赋予其重点所需的预编写步骤。 你完善了这个想法，确定了受众和范围，集思广益必要的步骤，并最终确定了大纲。 这为您开始写作提供了坚实的基础，还为我们的编辑提供了决定是否接受您的教程进行出版所需的信息。 在写作过程中大纲发生变化是正常的，要么是因为编辑的建议，要么是因为你在写作时的认识。 不要认为大纲是一成不变的，而是一个让你走上正轨的框架。
