介绍
DigitalOcean编辑团队在这里支持像你这样的作家:开发人员和工程师,他们希望与社区中的其他人分享他们的知识。
因为DigitalOcean不能接受我们提交的每一个教程,我们要求你在批准你开始写作之前看到一个建议. 我们不希望你在你知道你是否被接受之前写整个教程,所以我们要求详细的概述。
在本文中,您将看到如何为您的教程想法制定建议和概述。您将首先做一些准备,这将有助于您塑造内容,您将决定您希望读者实现的目标,然后您将定义将其带到那里的步骤。
步骤1 - 定义你的焦点
首先要决定的是你想写什么。 通常,你会从一个单一的词汇开始这个想法,例如: Nginx,或Helm,或React。 接下来,找到与词汇一起走的词汇:你希望用户用产品做什么? 或者用另一种方式说,读者的学习结果是什么? 在这个阶段,你会将重点从作家转移到读者。 而不是我想写什么?问题变成了读者想要完成什么? 找到合适的词汇会回答这个问题。 词汇如学习或理解不是教程的好主题,因为他们没有可衡量的结果。 相反,考虑这样的词汇:
- 安装
- 创建
- 配置
- 集成
- 部署
- 监控
- 测试
- 安全
- 自动
- 故障排除
几乎所有的DigitalOcean教程都以How To的词开始,这为您提供了选择一个好的词汇的引导。
这为您提供了读者学习目标的明确陈述,这也应该帮助您定义您的标题,这两者都是我们将在您的提议中请求的信息。
一旦你已经正确定义了主题,你可以把注意力转向你写给谁。
步骤二:对观众做出决定
下一步在策划教程时要考虑的是谁会读它?谁会从教程中受益最多,他们已经知道多少?他们已经知道多少会决定你需要提供多少背景信息,这会影响教程需要多长时间。
例如,教程 Initial Server Setup with Ubuntu 20.04假定很少有背景知识. 它解释了 root是什么,以及 SSH 密钥是如何工作的。
该教程 如何在DigitalOcean Kubernetes上逐步使用Flagger发布假定一个更有经验的读者。它假定读者熟悉Kubernetes, Helm和Nginx,并且已经配置了一个集群来使用所有这些技术。这使作者可以跳过这些产品的配置,并专注于Flagger,这是教程的主题。
美元(注)
** 注意:** 提前教程在提议的教程先进时是有用的。DigitalOcean 拥有超过 3000 个教程的库,任何教程都可以作为您提议的教程的先决条件使用。
美元
如果你正在写关于如何配置Kubernetes负载平衡设置的文章,你可能会认为观众应该包括使用Kubernetes的每个人,但如果你把观众集中在只有Kubernetes管理员,他们有足够的集群和足够的流量需要精细调整负载平衡器,你会有一个更有用的教程。
这并不意味着你的教程不会具有广泛的吸引力,你可以提供额外的背景,吸引其他技能水平的读者。
定义你的观众会给你一个想法,你需要涵盖多少内容,或者换句话说,范围。
步骤三:决定范围
与观众一样,DigitalOcean教程的范围应该是狭窄的。试着专注于一个任务。关于如何部署一个Node应用程序与React Front End和MySQL数据商店的教程有很多组件,还有很多步骤。我们宁愿看到一本关于如何部署一个Node应用程序(https://andsky.com/tech/tutorials/how-to-set-up-a-node-js-application-for-production-on-ubuntu-20-04)的教程。一旦第一个教程成功发布,你可以提出另一个使用第一个教程作为前提,并以这种方式构建一个更复杂的解决方案。
我们希望读者能够成功地复制步骤,所以更有可能使用狭窄的范围,您可以写一本涉及六个不同的服务器的监控教程,但读者需要设置这么多Dropplets,这可能不方便或昂贵。
同样,尽量避免使用需要多种不同的技术的教程,例如如何在 Debian 上使用TravisCI和Grafana监控来部署Flask应用程序的教程只对使用所有这些精确技术的读者有用,这限制了教程的使用寿命,如果其中一种技术被取代或不再受支持。
随着教程的限制被定义,您可以开始创建您的教程的框架与概述。
步骤4 - Brainstorm 任务
现在你知道你想写什么,以及为谁写它,你可以开始编写一个概述。 这个过程的第一部分是想想你试图解决的问题。 想想涉及的整体任务,以及你可能采取的个别流程。 例如,如果你在 Ubuntu 上如何安装 Nginx(How To Install Nginx)上写了一篇教程(https://andsky.com/tech/tutorials/how-to-install-nginx-on-ubuntu-20-04),你会包括一个sudo apt install nginx的步骤,但也有其他考虑。
- 调整防火墙以允许访问
- 验证 Web 服务器
- 管理流程
- 设置服务器块
这些步骤不是严格的安装 nginx过程的一部分,但它们对于正确的 Nginx 安装是必要的,这就是为什么教程增加了对基本文档的价值。
例如,你可能不会立即考虑调整防火墙,因为你的防火墙通常是正确配置的。当你考虑到它时,写下它。在这个步骤中保持包容性。想想可能很好或不严格相关的任务。一旦你考虑了你想要包含的一切,是时候组织起来了。
步骤5 – 将任务组织成一个概述
之前的步骤为您提供了在教程中包含可能的任务的列表,所以下一部分是组织它们。其中一些将是清晰的,因为操作流程:您必须在测试结果之前运行安装 nginx命令,所以安装步骤必须先来。有些步骤可能不那么明显:读者应该在安装后或之前配置防火墙吗?在读者的学习目标方面考虑每个步骤:该步骤如何帮助他们向整体目标进展?有些步骤不会有一个具体的地方,他们需要发生,这很好。
确保过程的每个步骤都实现了有形的东西,这意味着每个步骤都应该有一个有用的词汇。 如果你写了了解防火墙如何工作作为一个步骤,那就不会实现可以证明的东西。
例如,你需要一个Ubuntu服务器才能在它上安装Nginx,但这在另一个教程中被覆盖,所以你不需要一个单独的步骤。在这种情况下,你可以将设置Ubuntu 20.04服务器添加到前提列表中,并链接到现有的教程。
其他步骤可能太先进了,无法在范围内使用。您可能希望安装 Nginx 来使用它作为反向代理,但该设置与安装分开,并且在单独的教程中更好地覆盖。
通过添加有关每个步骤的一些细节来完成你的概述,用几句话告诉我们读者会做什么,为什么每个步骤都很重要,以及它如何与下一个步骤有关。
第6步:避免陷阱
你的概述有两个目的:它作为一个框架,将使写作过程更容易,它将让DigitalOcean编辑团队知道你打算写些什么,以便他们可以决定是否接受它发表。
- ** 背景步骤:** 如果你有一个步骤, 读者不做任何具体的事情, 或者一个步骤只是提供背景, 如果您想要提供某种技术常用的背景, 可以在教程的入门部分进行 。 如果你在解释读者为何要迈出一步, 例如,不是首先解释防火墙背后的理论,而是让读者使用命令来配置防火墙,然后确切解释他们为什么使用这些特定的命令. 读者若有与理论相接的亲身体验,学习得更好. (_ (
)* ** 未说明步骤:** DigitalOcean编辑在各种技术方面经验丰富, 在你的纲要中增加一些解释,将有助于我们了解这些步骤如何结合在一起实现你的目标。 类似
确定一个用户的步骤本身可能并不明确,但为了安全目的,可以添加数据库服务需要具有特定权限的专用用户。 在此步骤中,读者将创建该用户并设定权限。` 这样,我们就能知道为什么需要采取这一步骤。 - ** 重购:** 许多大纲都有一个步骤一,要求读者克隆一个回波,以获得一个样本项目来部署在教程中. 出于若干原因,我们避免了这种模式。 首先,我们需要确保补习课程终身可用。 (如果需要回购, 我们将复制到数字海洋社区网站, 因为安全原因, 我们并不要求读者使用尚未完全解释的代码。 第三,我们把每一块代码当作学习的机会,即使它与教学的主题没有直接关系。 如果您的工程包含一个 CSS 文件, 它过于复杂, 无法从教程中分辨, 请考虑简化 CSS 。 将样本项目保持在教程所需的最小值,可以将焦点保留在属于它的地方. (_ ( )* ** 漫长的步骤:** 有时你会有一个包括其他从属任务的步骤。 例如,你可能有一个步骤,要求将服务器上的信息序列化,转发给客户端,然后在渲染前将其解析. 如果你发现自己的台阶会从小标题中获益,那就应该把台阶拆分成两个或两个更小的台阶。 您的编辑器可以在此问题上帮助提供建议 。 ( _) (英语)
结论
在本教程中,你已经完成了定义你的教程并给它重点所必需的预写步骤。你精简了想法,识别了观众和范围,大脑风暴了必要的步骤,并完成了概述。这为你提供了开始写作的坚实基础,还提供了我们的编辑需要决定是否接受你的教程发布的信息。在写作过程中,概述改变是正常的,要么是因为你的编辑的建议,要么是因为你在写作时所取得的成就。