你是否在 Hashnode 或者 Dev.to 上写过技术帖子，又是否总想尝试新东西呢？如果是这样的话，有一件事情能帮你一解心头之痒：为开源项目做贡献。

我知道，我知道你肯定已经无数次在 Discord 群组里或在技术相关的社交媒体帖子中听到“为开源做贡献！”的呼吁。但是相信我，身为一名技术写作者，这真的是一个你积累经验的好方式。

一方面，你能参与一些公开展示的项目，这能帮助你向技术写作专业人士展现你的能力。

另一方面，和大家的普遍认识不同，实际上编写代码并不是为开源项目做贡献的唯一方式，你也可以利用自己的写作技能帮助项目维护者进行文档优化。

除此之外，为开源项目做贡献能够帮助你学习新的技术语言和软件，而这被美国劳工统计局描述为 技术写作者的重要技能之一。

还是无法说服你？没关系，在此指南中，我会探讨如何寻找需要技术写作者的开源项目，也会介绍通过技术写作能为开源项目做什么贡献，并且就如何公开展示这些贡献提出建议。

如何寻找需要技术写作贡献的开源项目

许多开源项目在文档方面都需要帮助，而你需要根据自己的兴趣、技术写作水平以及贡献机会来选择你将参与贡献的项目。

在寻找需要贡献的开源项目时，我强烈建议你向同事询问他们参与的项目。与朋友合作+参与开源项目，这难道不是一举两得吗！:) 在选择了项目之后，我建议你做这些事情：

1. 前往项目仓库的 Issues 选项卡。

2. 单击 Label 选项

3. 在文本框中输入 "documentation"，就可以啦！

现在如果你想寻找一些更具体的项目，我在这里列出了一些重点关注文档的开源项目：

The Good Docs Project

如果你正在寻找开源项目来积累文档写作的入门经验，我强烈建议你加入 这个群组. :) 他们有多个工作组，且关注不同类型的写作，包括创作文档模板供其他开发者在自己的开源项目中使用、优化组织的网站内容以及为社群成员已创建的模板做 QA （质量验证）。

Codecademy

如果你精通某种特定的编程语言并想向其他人分享相关知识，我强烈建议你为 Codecademy 的 文档 和 文章 仓库做贡献。他们基于不同需求提供模板，比如为特定章节提供新条目并更新/编辑现有条目。

Astro

如果你是 Astro 的狂热用户, 那你可以在他们的 docs repo 中分享该软件的使用建议，他们的文档组非常乐于与拥有不同经验水平的成员合作。

选择项目仅仅是其中一步，接下来让我们看看技术写作者为开源项目做贡献的不同方式。

技术写作者为开源做贡献的不同方式

恭喜！你已经选择了自己的贡献项目。现在，你需要决定如何利用自己的技术写作技能做贡献。

我知道这一步很难，但不要担心。现在，我们将讨论你能做出哪些不同类型的贡献。

修改 README 文件中的拼写错误和其他语法错误

README 文件是开源项目的重要基础，其中会描述项目的目标和贡献步骤，因此 README 文件应该尽可能表达清晰。

如果你在阅读 README 文件时发现逗号缺失或者句子表述不清，你可以向项目维护者发起 issue 并进行编辑（当然，前提是他们通过你发起的 issue）。

我在刚加入 EddieHub 社区的时候就是通过这种方式做贡献。这不仅仅是一种很好的自我介绍方式，也教会我根据特定受众来定制文档。当然，这不是为开源项目做文档贡献的唯一方式，让我们来看看另外一种方式！:)

创建内部文档风格指南

这需要创建一个指南，其中将定义某个开源项目文档的写作和格式标准，从而指导贡献者有效地进行开源项目的文档写作。

在该文档中，你将看见一些诸如标点符号的正确和错误书写方式、代码块格式化的特定方法以及产品文档的语气语调等信息。

Google 开发者文档中的缩写形式 便是一个很好的例子。

在看到 Document Write 的 YouTube 频道 中 Portia 的一则视频后，我决定撰写 一份针对 EddieHub 的 Linkfree 项目的文档风格指南。她在视频中谈论了开源贡献者，尤其想要将技术写作作为职业的贡献者，如何从这些风格指南中受益。

通过创建这份风格指南，我学到以下知识：

1. 以新的风格或语言编写: 由于 Linkfree 的主要受众来自英国，项目维护者希望使用英式英语来撰写风格指南。我之前从来没有使用过英式英语，所以需要重新学习单词的拼写、大写以及标点符号的使用，这是一个非常有趣的过程。
2. 使用新的技术工具或框架: MDX (Markdown X) 是贡献者用于维护 Linkfree 文档的一种技术语言。简单来说，你能在 Markdown 文档中使用 JSX （让你将 HTML 代码嵌入 JavaScript 的语法）。我曾短暂地使用过 Markdown，所以我能更轻松地使用这种语言来创建文档指南。

当然，撰写风格指南也只是为开源项目做文档贡献的其中一种方式，让我们再来看看另外一种方式吧！:)

添加产品教程

如果你善于指导他人，或者你在阅读开源软件教程时发现关键信息缺失，你可以考虑通过这种方式来做贡献。

Audacity 网站上的 tutorial 章节 就是一个很好的例子，而 Audacity 是一个免费的录音及音频编辑的开源软件。

作为开源社区的新人，我发现大多数入门级的内容并没有提供关于贡献者如何在找工作或面试时利用开源贡献经验的建议。因此，我在 Github 上浏览 OpenSauced 的仓库时，发现这些内容对于他们的 Intro to Open Source 免费课程很有帮助。

于是，我将这种想法传达给了公司的用户体验经理 Bekah，创建了一个拉取请求，并且最终 它被合并啦！

我强烈推荐你去做这种类型的贡献，因为练习的绝佳方式就是简化技术文档，使之便于全球不同技术水平的读者阅读。同时，这也能培养你注重细节的能力。

那么，在你着手通过参与开源贡献来积累技术写作经验之前，你现在还需要考虑一件事。

展示你的作品

当谈及展示作品的重要性时，Austin Kielon 说得最好：“展示你的作品吧”。

我想说的是，我们是大声疾呼的作者，通过文字展示内容是刻在我们骨子里的东西，那为什么不展示自己的作品呢？

你可以通过撰写博客、在社交媒体上发帖子，或者录制一集播客来展示你参与的项目。

如果你想通过一种更系统化的方式来展示作品，我推荐你使用 OpenSauced 免费的 Chrome 拓展插件。利用这款工具，你能追踪你正在做贡献以及计划做贡献的 GitHub 开源仓库。

除此之外，这款工具还具备 “Highlights” 功能，你可以选择将某些贡献发布到个人档案，并将它分享在领英和推特上。了解详细操作信息，请查阅 教程。

在你参加工作面试时，这些能作为你很好的作品参考。除此，这也能为其他开源贡献者提供灵感。在将我为 Linkfree 创建的文档风格指南分享到推特后，我的一位同事非常喜欢它，所以她认为为她的项目也创建一份文档风格指南是一个不错的做法。于是在她的邀请下，[我创建了一份文档风格指南]。(https://github.com/AccessibleForAll/AccessibleWebDev/blob/main/docs-style-guide.md)! :) 所以，永远不要低估展示作品的力量！

朋友们，这就是我为你们提供的关于如何通过参与开源贡献提升技术写作能力的指南。我知道，你在真正动手做的时候可能会害怕，尤其在刚开始的时候。但是，根据这些建议来实践并保持积极的态度，我相信你会成功的！

鸣谢

UXwing 提供的开源标志

Ylivdesign 在 Dreamstime上提供的技术写作图标

我在开源社区工作了将近5年，建立并推广了包括 Meteor 和 Apollo 在内的开发者工具。在这段时间里，我发现写博客是传播思想最有效的方式之一。

一篇博客文章不需要像视频或会议演讲那样花很长时间来准备，它很容易上手，而且受众面很广。我个人也从写作中受益颇多：帮助我整理思路以及向他人传授我喜欢的技术的同时，也让我被更多人认识。

自从2014年发布我的第一篇博文以来，到目前为止，我已经在Medium上写了68篇文章。有些文章的浏览量超过5万，我的粉丝数也超过1000人。我也为我的朋友和同事编辑过许多文章。在这段时间里，我掌握了一些从提出概念到最终完稿的方法策略。

在本篇文章中，我将介绍我写文章时涉及的五个步骤：

1. 找到一个好的主题并围绕主题写作
2. 确定你的写作目标和读者对象
3. 文章有开头、中间、结尾
4. 获取反馈并迭代文章
5. 添加点睛之笔：包装、发布和推广

让我们直接进入第一个步骤！

1. 找到一个好的主题并围绕主题写作

除非有东西可写，否则你没法开始写文章！在我和那些想要开始写博客的人交谈时发现，他们的主要障碍往往是没东西可写。

最简单的办法是写你知道的东西。如果你花了很多时间学习某件事情，并且你认为你可以在几分钟内将它解释清楚，那么你就可以为你的读者提供很多价值。

另一个办法是在一个你认为缺乏内容的领域写作。比如，现在关于如何申请技术会议的文章很少，那么写这方面内容就可以填补技术社区的空白。

这里有一些具体的文章类型，你可以去看看。例子来自Apollo博客上GraphQL相关的文章：

1. 实现特定目标的分步操作指南：“在React Native中使用Flatlist创建可滚动列表” 或者 “通过Apollo和Recompose简化React组件”。这类文章很适合那些希望读懂就上手，然后迅速离开的读者。
2. 关于特定主题的深入调查：“在GraphQL中使用nullability” 或者 “GraphQL查询的剖析”。这类文章适合那些有时间慢慢深入学习的读者。
3. 就一个常见主题列出多项实用因素：“调用GraphQL API的4种简单方法” 或者“静态GraphQL查询的5个好处”。这类有趣又轻量的内容，适合碎片式阅读，读者无需阅读全部内容。

现在，我想消除一些你们常见的担忧。

1. 这个主题的内容已经有人写过啦。 不要因此而退缩。即使你的选题已经有人写过，你也可以写出自己的观点，或者基于你自己的情况写出更具体的内容。
2. 我的想法不够有趣。 我的朋友和同事最后都没有写，就是因为他们担心他们的结论可能会很无聊或者没有创意。这种感觉是正常的！如果你是某方面的专家，那当然你写的结论会很无聊……那是对你而言。关键是你的读者还并不了解这些结论。

说了这么多，说到底，很难预测哪些话题会让一篇文章成为热门。决定一篇文章成败的往往是要行动起来开始写而不是要精选一个完美的话题。我主要的建议是，多尝试写不同的东西，看看哪些效果还不错。

2. 确定你的写作目标和读者对象

明确主题后，现在你需要确定你的读者对象和写作目标。谁会阅读这些文章呢？他们想从中获得什么呢？

你的目标应该很明确具体，这样你才能集中精力专注在一个主要的观点上。就本篇文章来说，目标不可能只是“写博客”，我需要一个更明确具体的目标：

• 读者对象: 想开始写博客的人，尤其是想写技术博客却还没写过的人。
• 写作目标: 提供一套具体的写作步骤和指导方法，便于他们开始行动起来。

有了这些以后，就要专注于文章的重点了，删掉没有意义的内容，不要增加看起来有关联但很多余的细节。我发现那种阅读时间在5至10分钟，相对简洁的文章是最好的。

了解读者背景可以帮助你基于读者现有知识水平去定制化写作。而且可以帮助你决定如何去发布和推广你的内容。比如，我就希望在freeCodeCamp上发表这篇文章，因为在我的目标读者中，可能已经有很多人在这个专栏阅读文章了。

3. 文章有开头、中间、结尾

当一篇文章偏离了自己所期望的方向时，就会给人感觉很迷惑。在虚构短篇小说里，情节曲折可能是一件好事。但是，在技术文章里，应该秉持所见即所得。简单舒适的文章结构会更益于读者理解和消化。

开头介绍

文章的第一段或者前两段将决定读者是继续读下去还是放弃阅读。开篇，先介绍一下背景，帮助读者了解你这篇文章的定位。然后，告诉读者他们能从这篇文章获得什么。开头设置悬念，把大揭秘留到最后可能会吊起读者胃口，但是注意，如果运用不恰当，是没法吸引读者坚持读到最后的。

中间细化

你已经告诉读者他们能获得什么了，那就如他们所期去写吧。你可以根据需要自行细化内容，做好结构标注，引导读者阅读。使用大量标题、编号列表和格式，帮助读者了解自己读到哪儿了，同时便于他们跳转到最感兴趣的部分去阅读。

最后结论

文章注意不能虎头蛇尾。如果读者都读到结尾了，说明他们确实被吸引了。可以在结尾快速总结所学内容、对读者的坚持给予鼓励，甚至可以呼吁读者受鼓舞后采取行动。

我在此建议的文章结构并不是最有创意的，当然还有其它的结构方式。但是与读者沟通最直接的方式就是文章结构足够简洁。

4. 获取反馈并迭代文章

读者读过你的文章，你才会了解他们到底想从你的文章中获得什么。这是对你假设性主题、目标、文章细节和结构的真正考验。如果你想有一个好的结果，就不能跳过这一步。

当你要求反馈时，你可能会觉得自己在强加于人，或者你可能担心反馈会是负面的。但是实际上读者比你预期的更乐于帮助他人。最好在你对外发布你的文章之前，就知道如何能够优化你的文章。在我整理这篇文章时，我就得到了一些超级有价值的反馈，这些反馈使得这篇文章更精炼。

你应该问你的文章审阅者一些什么问题呢？我的主要建议是尽可能地不设限。尽量不要提前解释你的目标。把草稿原封不动地交给审阅者，然后问他们从中得到了什么或者有什么修改建议。当读者在网上看到你的文章时，他们就因为已经被考虑进目标读者中而自然认可你的文章了。

反馈主要是要验证一件事：这篇文章能否实现你在第2步中决定的目标？如果不能，那就一直迭代，直到你确信目标能实现为止。

5. 添加点睛之笔：包装、发布和推广

现在你有了想法、目标、结构和反馈，是时候打磨好一切准备发布了。

包装

想一个出色的标题和副标题，并确保文章至少有一张配图。文章分享到Twitter或Facebook时，读者会看到这些标题和图片的。这也是吸引读者阅读的机会。

同样重要的是，你的文章要让人觉得专业，这样你的内容才能真正出彩。文章中应该避免拼写错误、语法错误或者奇怪的格式。如果你有善于发现细节的朋友，可以请他们先阅读一遍文章，然后你再发布出去。

freeCodeCamp专栏写作指南也提到了写作风格和样式的技巧。既然你已经在文章中投入了这么多精力，那么额外多付出一些努力去打磨它，让它有更大的影响力也是值得的。

最后，请务必注明你引用了谁的作品或者谁帮助过审阅和编辑你的文章。

发布

你就快大功告成了！选择最利于触达读者的平台来发布文章。通常，Medium是一个发表技术文章很好的平台，在这儿你的文章很容易被读者发现。

为了效果更好，试试将你的文章发表在有助于分享你内容的平台上-基于这种考虑，我选择了freeCodeCamp。因为我认为这个建议是考虑了freeCodeCamp上的读者人群。如果你也想这样做，这里有他们给出的提交文章的指南。你感兴趣的发布平台也可能正在寻找相应的文章，所以大胆去联系吧！

推广

即使你真正发布了文章，工作也还没有结束！如果你想要读者看到你写的东西，并从中受益，那就要把文章分享到读者经常阅读的地方。像包括Facebook群组、Reddit、Hacker News、LinkedIn或者其它任何平台。另外，也要在你自己的社交媒体账户分享你的创作，比如Twitter。你的朋友会很乐意阅读、分享和点赞你的文章。

现在，你已经大功告成了！去喝杯咖啡或者散散步吧-把一篇博客文章从头到尾写完可不是一件小事。阅读来自社区的所有反馈和回复。当你有了另一个想法时，又继续这样来一遍吧！

除了实践，没有别的选择

我们刚刚把关于撰写技术博文，从提出想法到发布终稿最重要的五件事梳理了一遍。现在你也已经读完了，试一试这些建议吧，看看会有什么收获。

我再提最后一点建议。在过去三年里，我从博客中学到的重要的东西是我绝对无法预测哪些内容会爆火，哪些内容会平淡无奇。有时，我会花几天时间写一篇文章，打磨每一个细节，但它却没有引起多大反响。相反，“GraphQL vs. REST”，这是我的有史以来阅读量最多的一篇文章，它却是我在深夜几个小时内写成的。

所以，即使你的第一篇、第二篇或者第三篇文章没有成功，也要继续尝试写新的东西。把你的想法写出来，并不断优化。世界想听听你要说点什么，去告诉他们吧！

非常感谢Anvisha Pai、Angela Zhang、Katie Siegel和freeCodeCamp的编辑人员，帮助审阅这篇文章。

你或许以为软件开发全是围绕写代码进行的，但事实并非如此。这项工作中很大一部分内容是与他人沟通。随着越来越多的工作转向远程办公的形式，书面交流变得越来越重要。

“在一个工程师开始工作的最初几年里，他大概会花 30% 的时间在写作上，而中层管理工程师每天花费 50% 至 70% 的时间写作；高级管理人员花在写作上的时间占到了每天的 70% 以上，甚至 95%。” —— Jon Leydens

我在去年离开了我作为软件工程经理和首席技术官的职位，成为了一名全职写作者。在软件行业工作了十年后，我拿着银行里六个月的存款，决定冒险改变我的职业。

很高兴地说，新职业的一切到现在为止都非常顺利，我的公司最近也因我们的技术文书工作而被 TechCrunch 报道。

在创办 Draft.dev 之前，我已经在外面写了很多年的博客和教程，所以我对自己的写作能力相当自信。但在公司创立后，我依然学到了很多。我也遇到了许多优秀的导师和同行，他们一路走来给我提供了写作方面的建议。

在这篇文章中，我想分享一些我经常与其他软件开发者分享的写作技巧。他们将帮助你克服所有新写作者会面临的阻力，希望能给你带来尽早开始写作的信心。

1. 从你知道的东西开始写起

“没有人生来就是伟大的作家。从你目前所知道的东西开始写起，并与社区分享它们。你会惊讶于你能影响多少人的生活。” —— Eze Sunday（软件开发人员、技术作家）

要想成为一个比现在更好的写作者，你必须比以往更频繁地写作。任何技能都是如此，但对于写作来说，这可能更难，因为你不能只是在一张纸上随意堆砌一些词藻。你必须有写作的 主题。

克服这一障碍的最常见的建议是，开始写你已经知道的事情。

在 Strapi 从事开发者关系的 Daniel Phiri 告诉我：“从你刚解决的问题开始，不管你认为它有多微不足道。”

他也指出，即使一个话题已经被广泛地写过了，你的作品也可以与众不同。“写作是关于视角的，我们每个人的视角就像我们个体本身一样独特。”

Eze Sunday 重申了这个观点：“世上的确有很多文章，但是，在你刚开始的时候，你会发现没有多少好文章会以你喜欢的方式来解释事情。”

2. 专注于少数高质量的作品

“质量胜过数量”，James Hickey 如是跟我说。“专注于写高质量的文章，而不是写一堆 一般 的文章……如果你的内容质量只是 一般，没有人会对它留下深刻印象。”

James 是一位资深的 .NET 开发人员、微软 MVP、作家和演讲者，家里有八个小孩，所以对他而言，找出时间写作总是一个挑战。他的解决办法是谨慎选择他要写的内容，一旦他定好主题，他就会深入研究。

这种做事风格在他的作品中可见一斑，比如这篇登上了 Hacker News 头版的关于电子商务数据模型的文章。

我同样发现，我最受欢迎的一些博文正是那些真正深入到某个主题的文章。

举个例子，我个人博客上最受欢迎的文章之一是这份 4500 字的 API 开发指南。我承认我写了许多比这短的文章，但要把一件事讲透彻，有些话总是要说的。

3. “完美”是“足够好”的敌人

从另一方面来讲，不要让推动你写出最好内容的动力阻止你按下“发布”键。

在 FusionAuth 负责给新开发者的信和开发者关系的 Dan Moore 提出了这个建议：

“‘完美’是‘足够好’的敌人。为了解决这个问题，我喜欢为自己的写作限时，即使当时间限制到了的时候文章还不完美，我也会发布它……或许你的文章不能登上 Hacker News 的头版，但我能保证，如果你不发表，没有人会读它。”

许多新手作家过份地在意文章的细节，而不是他们想法的结构与组织。说实话，如果读者能跟上你的逻辑，他们很有可能并不会在意那些拼写和语法错误。

Alpha Particle 公司的首席技术官 Keanan Koppenhaver 告诉我，过度在意完美的语法，可能会使你的作品看上去太过于机械化而毁掉它：

“我们常常容易陷入试图使你的作品达到最好的状态：完美的语法、伟大的句子结构等等。我曾使用海明威编辑器等工具来使我的写作‘技术上正确’，但当我重新阅读我的作品时，它看起来很陈旧，就像由人工智能创作的一样。”

4. 留出时间定期写作

“你要像对待任何习惯一样对待[写作]，并给它留出时间。我发现有件事很有帮助，那就是在早上做的第一件事就是写作，你甚至可以早一点起床。我不是一个习惯早起的人，但我仍然觉得这是我最有精力去写作的时候。在这个时刻，没有其它事情会占用我的精神。” —— Adam DuVander（EveryDeveloper 的创始人）

虽然前面说过，但我要再次重申这一点：要想成为一名更好的作家，你必须更经常地写作。不过，这对每个人来说都是不同的。

就我个人而言，我每周都会在日历上定好写作时间。我发现，当我专注于写作 4-8 个小时时，我会达到最佳的工作效果，而不是在试图把写作塞进一天中零碎的休息时间。

当然，并不是所有人都像我这样。Stephanie Morillo 是一位技术交流专家，她就适合在更短的时间段里写作。

“我用时间块（timeboxes）来管理写作：如果我计划写一份讲稿或一篇博文，我会在一天或几天内留出几个 30 分钟的时间段，坐下来写。”

她指出，这些较小的时间块对她的日程安排来说更现实，它使她能够取得进展并增加产出：“无论你在一天内写 10 个字、100 个字还是 1000 个字，你仍然在朝着你的目标取得进展。”

另一种策略是让写作成为一种日常习惯。经营 Developer Avocados 通讯的 Alex Lakatos 在去年的部分时间里完成了一个每日写作挑战：

💡 平均下来，形成一个新的习惯需要 66 天。现在离 2021年还剩 65 天，我们何不早点开始进行我们的新年计划呢？

以我的计划为例：我正在努力持续地发布内容，所以在今年剩下的时间里，我将尝试每天至少写 100 字。 pic.twitter.com/M0dHrJ36ef

— Alex Lakatos 👨‍💻🥑 (@lakatos88) 2020 年 10 月 28 日

关键在于，每个人都是不同的，没有一个足够普适的方法来规划预留给写作的时间。Keanan Koppenhaver 跟我说：“最主要的事情是要找到一个时间，让你的大脑能够集中精力、有创造力，真正把你的想法以连贯的方式记录下来。”

5. 管理你的期望值

“诚然，让别人读你的文章是很好的，但为自己而写作也是非常有价值的，而且你能保证绝对会有人读它。因此，首先也是最重要的事就是为自己写作。” —— Dan Moore

看到自己写的文章如病毒般传播所带来的快感是非常难以自拔的。在过去十年中，我发表了数百篇博客文章，但只有其中五篇登上了 Hacker News 的头版。这并不算什么令人印象深刻的点击率。

这就是为什么你应该主要是为自己而写作。你甚至不需要像 Stephanie Morillo 所说的那样公开发表东西：

“坚持写日记，写下关于工作、你的一天、你的生活、你的情绪的笔记。写日记让你有机会在没有自我意识的情况下写作，因为你在写作时不需要考虑听众；你只是为自己而写。”

最后，当你开始写作时，必须牢记你的目标。你是否只是为了记录自己的学习成果而写作？你是想推广一本书、课程或产品吗？你要通过写作获得报酬，还是只是为了好玩？

Adam DuVander 指出，对自己的这些期望保持诚实是至关重要的。他告诉我：“决定写作是作为副业还是主业，这两种选择都是可以的，但你应该设好你的期望值……在工程职位上有许多地方要用到写作。”

结论

你的前100篇博客、视频、帖子、推特、生活、播客、创作可能都是垃圾

克服心里的障碍，去做吧！先过了这 100 关再说

反正几乎没有人会看到它，就把这当作是练习吧

这就是你为创作而付出的代价

— The BKH 🤳🏾 (@thebkh) 2020 年 12 月 12 日

正如 Brian Kofi Hollingsworth 在上文所说的，只有当你开始做一件事，你才可能变得更好。无论你是想利用写作来使你的事业更进一步、赚取副业收入、还是帮助社会上的其他人，如果你想变得更好，你就必须开始多做。

你对那些希望成为更好的作家的软件开发者有什么好建议？如果你有什么要补充的，我很乐意在推特上听到你的声音！

谷歌有一门技术写作课程，我最近刚学完这个课程并且非常喜欢。课程大约需要4个小时，并且配套有一些实操练习，可以检测自己的学习效果。

我将简要说明我学完这门课程后学到了什么，同时也会总结出其中最好的部分，这样你就可以了解这门课所涉及的大概内容。

我会说到一些英语的语法规则和语言学内容，但我都会提前做解释，这样，可以保证我们的理解是一致的。要完成这门课程，你只需要有“一点点英语写作能力”就好，而“不必特别擅长写作”。

开始进入主题吧。

前言

首先定义本文将会使用到的一些术语：

• 名词 用于称呼某物。例如凯夫人、埃菲尔铁塔或者经理。
• 代词 用于代替名词。例如我、你/你们、我们、他们/她们/它们、他或它。
• 形容词 用于修饰名词。例如友好的凯夫人、锈迹斑斑的埃菲尔铁塔或者不错的经理。
• 动词 表示动作或状态的词，例如打架、奔跑、打字和吃。
• 副词 用于修饰动词。例如打斗猛烈 、怯懦地奔跑、一个劲儿地打字和胆怯地吃东西。

清晰

清晰是说你写作中的观点是否清晰。技术写作的首要关键就是清晰。

代词用法

使用代词时，一定要确保代指事物是清晰明确的，不然很容易让读者混淆。例如这样：

C++是一门相当古老的语言，但JavaScript也有些年代了。不过，我还是喜欢它。

啊？你到底喜欢什么？C++还是JavaScript？这里的代词并不明晰。

要明晰代词的用法，可以像这样：

C++是一门相当古老的语言，但JavaScript也有些年代了。我真的喜欢C++。

一般来说，在校对时，如果不清楚代词指的是什么，那就用名词而不要用代词。这个或者那个特别容易引起歧义。无论什么时候用这类代词，确保指代明确。

习语

习语是描述事物时常用的短语。但有些习语并不适用于世界各地的读者，因为习语是你的地区/语言所特有的，尽量避免在技术写作中使用习语。

没有人能一来就理解围着粥边转、咀嚼肥肉或者给牛充气这些习语隐含的喻义。直白说你的意思就好了，尽量使用简单的类比，不用习语。

表达简洁

简洁度是指你写作表达的简短清晰程度。

优秀的软件工程师在优化工作时，会在编写代码上花尽可能多的时间去删除代码。写作同样如此。通常，

• 代码越短越易于他人阅读
• 代码越短越易于维护
• 额外的代码行会引入额外的问题

所有这些要点也都适用于你的技术写作。

有时，打磨文章和精炼表达需要花时间，你必须真正地对文档精雕细琢。甚至你可能需要校对多次——但，这都是值得的。

较短的句子也能鼓励读者继续阅读。一大长段太吓人了吧？长段有时会让读者望而生畏。有的读者看到一个段落足有上千字，就会直接退出页面。

删除“在（某地）存在一个”和“在（某地）存在多个”

在写作过程中，“在（某地）存在一个（there is）”和“在（某地）存在多个（there are）”几乎都可以删掉，让你的观点更简洁。

这2个说法通常很泛在并且让读者感到厌烦。改写一下句子吧。以下是一些示例：

• 在软件和硬件之间有很多重叠的地方。
• 在JavaScript中不存在多线程。

我希望你也认同改后的句子读起来更好：

• 软件和硬件有很多重叠的地方。
• JavaScript没有多线程。

尽量少用形容词和副词

形容词和副词常用于小说和诗歌等描述类和创造类写作中。

谷歌技术写作课程中，举的例子是把“草”改写为“青翠茂密的草”或者把听起来毫无生机的“头发”改写为“丝滑飘逸的头发”。

问题在于形容词和副词的定义常常很粗略，它们可能会让技术写作看起来像是营销写作。

在生产模式中，代码运行速度极其快。

对比：

在生产模式中，代码运行效率将提升225%。

希望你也认同改写后的句子更精准且可量化。

使用列表

一个长句里包含很多元素时，你可以把长句拆成列表形式。例如，如果你要列举某项技术的好处，你可以说，X是一个不错的选择，因为：

• 它是轻量级的
• 它速度很快
• 它容易使用

虽然这是一个简单的例子，但你理解我的意思了吧。现在这样比一个冗长的句子更易读，你也不会失去你的读者或者流量。

正确使用列表

如果你觉得某个地方确实可以使用列表，那正确使用很重要。可以像这样使用有序列表：

1. 这是我的有序列表
2. 它是不是很美观？

或者也可以像这样使用无序列表：

• 这是我的无序列表
• 看起来不一样，但仍然很酷

所以你应该使用哪一种列表呢？

像食谱这种顺序很重要的话，那就使用有序列表。也可以试着在每个序号后面使用一个命令式动词打头，强调列表中的步骤说明：

1. 打开烤箱。
2. 烘烤蛋糕。

无序列表适用于其它所有内容。

列表结构保持平行

现在你应该能够正确使用列表了。下一步，要充分利用列表功能，你需要让每个列表的结构平行。什么意思呢？

所有列表项目应保持相同的：

• 语法和标点符号
• 逻辑分类（所有列表项目逻辑上属于同类别）
• 大小写规则

举一个错误的例子：

• c++
• JAVASCRIPT？
• Rust！
• 巧克力片饼干（chocolate chip cookies）

这个例子违反了上述所有规则。“巧克力饼干”在逻辑上不属于这个列表、每个元素的大小写不一致、标点符号的使用未统一（不清楚为什么“JAVASCRIPT”以“？”结束，而“Rust”以“！”结束）。

使用主动句

句子通常由主语、宾语和谓语组成。用几个句子来测试一下吧：

我写了一个故事。

我是主语，故事是宾语，写是谓语。

我真的羡慕杰克的工作。

我主语，杰克是宾语，羡慕是谓语。

• 主语是指做事情的人或物。
• 宾语是指被做的事情。
• 谓语是指主语对宾语发出的动作。

上述所有例子使用的是主动句，因为是主语对宾语做了动作。所以我们把这些例子改为被动句的话，那就是：

故事是由我写的。

杰克的工作引起了我的羡慕。（或者杰克的工作被我羡慕。）

你应该使用主动句，因为除了表达会更加有力和直接以外，

• 也更易于阅读。人们读到被动句时，还必须付出一些心力，将被动句转为主动句。所以，为了便于阅读，写作时使用主动句而不要用被动句。
• 读者更熟悉主动句，因为我们大多阅读的都是主动句。
• 被动句有时会迫使读者去猜测，这个句子里谁做了什么，让人费解。
• 主动句一般比被动句短。

通用写作技巧

让我们看看如何最大程度地优化每个部分来写出一篇精美的文章吧。

句子

开发人员熟悉代码编写的单一性原则，这个原则在写句子时也同样适用。

一个观点表达简明清晰后，再写下一个句子。不要有大量的和这个与和那个，甚至可以把最后一句进行拆分。如果你后面写句子，记得把每个和后面的文字拆开，单独成句。

段落

段落应该有一个明确的开场白句子，解释本段落的中心思想。

你也应该清楚地回答以下问题：

• 你想表达的是什么？
• 为什么这很重要？
• 读者应该如何利用这些知识？

我们可以举个例子，应用上述所有技巧。

garp()函数返回一个数据集的平均数和中位数之间的差值。很多人坚信不疑的是平均数总是不会错的。然而，平均数很容易受到几个非常大或非常小的数据点的影响。

调用garp()来辅助确定几个非常大或非常小的数据点是否对平均数影响过大。garp()值相对较小时，平均数更可取。

行话和认知语境

行话是特定领域使用的专门术语。

投资者可能会谈论W8-BEN表格或者SPAC。但如果你是圈外人，就不知道他们在谈论什么。

尽可能删除所有的行话和缩略语，只给出简要解释就好。

尽量让你的文章平实简单，但对于你讨论的内容仍然需要解释到位（不能过于简化！）。如果你写得有难度或者复杂让人难以理解，那它就帮不到任何人。

不要对认知语境做假定。如果你想谈论某件事，要么解释它，要么尝试给一个相关的优质链接。有些人把预先假定对方的认知语境称为知识的诅咒。

要假装读者比你知道得少，这样有经验的读者可以直接略过他们已经知道的部分，而萌新也不会感到困惑。

遣词用字

英语是技术写作的主要语言，却不一定是读者的母语。尽量坚持使用常用的、简单的英语词汇。

不必使用那些多音节的大词，那样会显得华而不实。

元信息

写一个简介

写作之前，在开头简要说明你要写的内容。这有助于读者往下阅读之前清楚知道你即将讨论的内容。

根据读者不同而调整所写内容

试着让你的文档适合对应的读者。在 dev.to 上，你可能用一种写作方式；在freeCodeCamp文章专栏上，你可能会用另一种写作方式。

根据读者不同而调整所写内容。例如，如果你要向更多读者解释你公司的架构，因为你的读者不像你同事知道那么多，你必须把事情解释得更透彻。

有时，你甚至可能不是为技术人员写作，那就需要用一种不那么复杂的方式来解释事情，帮助读者理解。

总结

简要概述一下本文涵盖的内容：

• 通篇结构试着保持一致
• 避免使用模棱两可的代词
• 多用主动句
• 表达简洁
• 每个句子写一个观点
• 使用列表
• 注意删除不必要的词语
• 不要使用复杂的英语或者行话
• 保持列表结构平行
• 段落首句为概述句
• 根据读者对象确定写作内容
• 文章开篇点明主旨

结语

我希望这篇文章解释清楚了那些我从谷歌技术写作课程中学到的有用概念。

我打算尝试挑选一些课程里给到建议的相关内容，将其应用于我的写作中，我希望这也能帮到你。在这里我发现了一些对我有用的规则，这些规则可以用于我制作的文档或任何技术写作内容。

文章中提到的谷歌技术写作课程可以在这里找到。

如果你喜欢这篇文章，并且还想看更多，可以在推特看看我的写作分享。

技术写作帮助你与他人分享你的技术知识和经验。技术写作在展示你的技术能力和才能的同时，也可以强化你对所写主题的了解。

在这篇文章中，我将阐述想成为一名技术文档工程师，你需要知道什么。我们将了解什么是技术写作、技术文档工程师需要的技能、如何成为一名技术文档工程师，以及了解一些能帮助你真正精通技术写作的技巧。

什么是技术写作？

我们可以用很多不同的方式来定义技术写作。但是 Grammar 上的定义是最有用的，它准确地解释了技术写作的含义：

“技术写作是作者就一个特定的主题写作，这个主题要求具有指导性、指示性或说明性作用。”

简而言之，技术写作涉及对某一特定主题直截了当、易于理解的说明和指示。

技术文档工程师需要具备什么技能

在那些曾经想要成为作家的人中，存在着一种常见的假设，即他们无法写出好文章是因为他们天生就没有写作天赋或写作技能。这就衍生了一个问题：作家是天生的还是靠后天培养的？

我很好奇其他人对这个普遍的假想是什么看法，于是我在推特上发了一条信息。

阅读每个人的观点都很有意思。大部分人说他们相信作家是天生的，另一部分人持反对意见，认为作家是后天培养的。有趣的是，还有一部分人认为作家既是天生的又离不开后天培养。很疯狂对吧？

我相信你很好奇我对此的看法，那么我将在下文告诉你。😉

我相信任何人，无论是否与生俱来拥有某种能力，都可以通过学习成为一名优秀的作家。我知道我不是生来就有写作天赋，所以我决定更加用心地学习如何写作。

说实话，你今天看到的大多数技术文档工程师很有可能都必须通过培养或学习特定的技能而变得擅长写作。

现在进入正题😃，要成为一名成功的技术文档工程师，你应该培养以下五项必备技能：

知道如何写作

我知道你可能会觉得困惑，为什么说写作是成为一名技术文档工程师所需的技能之一。你可能认为技术写作和写作是一样的，但是其实它们并不一样。

一般情况，写作就是使用符号（字母表的字母、标点符号和空格）以可读的形式传达思想和想法的过程。而另一方面，技术写作就是更具体地从逻辑和技术上来分享或表达你的想法、观点、指示和建议的过程。

每个技术文档工程师的首要技能是能够用他们首选的语言进行写作交流。例如，如果你打算用英语来写技术文章，你需要知道英语是如何构词和交流的。

想要更好地写作吗？试试以下步骤：

• 学习你首选语言的语法和语言规则，以便交流。
• 明白插图在写作中的作用。
• 多阅读！相信我，阅读将帮助你扩大你的词汇量。
• 最重要的是，使用你首选的沟通语言进行写作。

了解你的读者

识别和了解特定读者，并为他们定制输出你的内容将使你的文章或文档脱颖而出。这就是为什么你需要了解你的读者。

你了解你的读者后，就能写出为他们量身定做的文章，满足他们的需求，从而自动有效地传递信息。

那么，你如何才能了解你的目标读者呢？

问问自己关于读者的问题

你需要问自己这样的问题：“谁是我的读者？他们为什么要读这篇文章？他们希望从文章中得到什么？”

例如，在我开始写这篇文章之前，我问了自己这些问题，并得出了以下答案：

• 谁是我的读者？是那些想要成为技术文档工程师的人。
• 他们为什么要读这篇文章？为了学习成为一名技术文档工程师所需的必要技能。
• 他们期待获得什么？可以帮助他们开始行动并最终成为技术文档工程师的一切东西，比如技能、技巧、步骤、建议等等。

当我想清楚这些问题的答案，我就能够定位我的目标读者，就是那些初学者。这有助于我打磨这篇文章并帮到你。

使用正确的术语

如果你的目标读者是初学者，你应该使用容易理解的术语。你也可以添加具体的例子来帮助读者理解。

给你的文章或文档取一个有用的标题或名称

文章名称应具有描述性并对读者有帮助。

例如，当内容是关于 React 中的元素渲染时，就不要将文章命名为《深入了解 React》。这样会让那些期望在阅读完你的文章后能了解 React 所有知识的读者失望。

相反，想一个具体的标题，准确描述你文章中所写的内容，如《如何在 React 中渲染元素》。

培养你的技术能力

作为技术文档工程师，你的目标是帮助读者以最直接的方式理解高度复杂的过程或概念。

要做到这一点，你需要熟悉你所写的主题。这意味着如果你想写一篇关于 React.js 的技术文章或文档，你应该做到自己也会使用 React。

我将以阿尔伯特·爱因斯坦（Albert Einstein）的这句流行名言来结束本节：

如果你不能向一个六岁的孩子解释它，你自己也不会理解它。

这句话也呼应了在向别人解释你的主题之前，彻底理解主题技术细节的必要性。

能够做好研究工作

是的！技术文档工程师并非无所不知。所以，即使你可能熟悉一项技术，有时你也必须研究一种语言或框架，以便在你开始写作之前更好地理解所写主题。

这将确保你的文本是准确的并能最有效地传达必要的数据。你肯定不希望分享虚假或令人困惑的信息。

你应该如何进行研究？

研究的方式包括在你喜欢的搜索引擎上提问、请教对该主题了解的人（如果你认识的话）或者阅读书籍。

如果你决定使用搜索引擎的方式，就针对你想要发现的内容提问。例如，如果你想了解如何在 React 中使用 GSAP ScrollTrigger 插件，你的问题应该遵循这样的格式：“我如何在 React 中使用 GSAP ScrollTrigger 插件”。

如果你决定询问对该主题了解的人，记得要有礼貌，直奔主题。你可以遵循以下询问方式，而不是说完 “你好” 就等着对方回复后才提问。

“嗨，Rita，我叫 Edidiong。我知道你对使用 GSAP ScrollTrigger 插件非常了解。这些年来，我看过一些你的 CodePen 演示，它们看起来都非常棒。我很想知道如何操作 GSAP tween 滚动触发动画？如果你因为工作繁忙而不能回复，我完全理解。但如果你能回复，我将很感激。”

你可能觉得这是一条相当长的信息，但它包含了最重要的事情：你的名字、你对对方工作的钦佩、你的需求，以及你明白你无权占用对方的时间。

在研究阶段，你还可以选择阅读书籍。为此，你可以去图书馆或在线查找书籍阅读。

形成独特的写作风格

你有没有想过为什么人们会给一篇文章留这样的评论，“哇，看了你的文章，我终于理解了这个概念”，或是“我读了其他人写的文章都没理解这个概念，但读了你写的就豁然开朗了，谢谢你！”

如果你问我，我会说这是因为作者用了他自己独特的写作风格来写作。

这是什么意思？ 意思是每个人都是独一无二的。

所以，如果两个开发人员写同一个主题的文章，一些读者会更容易理解第一个开发人员写的文章，而另一些读者会更容易理解第二个开发人员写的文章。为什么会这样呢？ 因为两位开发人员都有自己独特的写作风格，不同的写作风格会适用于不同的读者。

那么，你如何才能形成自己独特的写作风格呢？

忠于自己，像一个作家那样，让你的思想自由流动，而不是复制其他作家的内容。是的，从他人那里获得灵感，但不要忘记你是谁！

事实上，人们的学习方式各不相同。有可能你写的内容刚好就是某个开发人员在真正理解一个概念前希望能阅读到的内容。

现在我们已经讨论了成为一名优秀技术文档工程师所需要的基本技能。我要说的是，这些技能可以慢慢习得，不用等到你全部都会了才开始写作—试着开始写作吧。

如何成为一名技术文档工程师

现在，我们来谈谈如何成为一名技术文档工程师。💃🏽

取得进展的秘诀就是开始。——马克·吐温（Mark Twain）

是的，我不得不从马克·吐温的这句名言开始说起，因为这是我们在接受新挑战时都需要记住的事情。下决心成为一名技术文档工程师是件好事，但是开始采取行动更重要。

我们来谈谈想成为一名技术文档工程师你需要做的四件重要事情。

参加技术写作课程

技术写作是一项紧缺的技能，雇主希望为团队招募到最优秀的技术文档工程师。参加技术写作课程的重要性被严重低估，但它其实是有必要的，因为你会了解到很多技巧，这些技巧可以帮助你成为一个更优秀的技术文档工程师。

参加完谷歌的技术写作课程后，我的技术写作技能明显提高了，所以我强烈建议你也参加这个课程或者其它类似写作课程。

阅读书籍和技术文章

读完一千本书，你将文思泉涌。——邝丽莎（Lisa See）

阅读是必不可少的，因为它将帮助你丰富你的词汇量、紧跟当前的趋势、了解写作界正在发生的事情、同时保持写作动力不竭。

为此，我强烈建议你去 freeCodeCamp、Hashnode、The Writing Cooperative 等网站阅读技术相关的文章。

开始写作

在写作中学习写作，在阅读和思考作家是如何塑造人物和编撰故事中学习写作。如果你不能成为一个读者，那就别想成为一个作家。——琼·M·奥尔（Jean M. Auel）

即使你参加了所有的技术写作课程，阅读了所有你能找到的技术文章，这也不会使你成为一个技术文档工程师。你需要实际写作才能成为一名技术文档工程师。

你可能想知道如何才能真正开始写作。好吧，我来告诉你。

首先，你需要想好一个你想写的主题。然后你应该做必要的研究，写出文章初稿，并校对文章（至少两遍）。准备就绪后，你就可以在你的博客上发布文章了。

你不需要从头开始建立你的博客，因为这会占用大量时间且分散你的注意力，使你无法专注于写作这件正事。就我而言，我用 Hashnode 创建了我的博客，因为 Hashnode 速度超快，它有一个强大的社区，并且允许你将博客映射到你自己的域名。

在你对写作得心应手后，可以申请成为 freeCodeCamp 的专栏作者。如果你通过审核，就可以在 freeCodeCamp 的平台上发布文章，以此接触到更多的读者。

坚持写作

坚持写作在帮助你成为一个更好的作者方面起着巨大的作用。它可以释放你的生产力，转变你的观点，建立你的信心。

你一开始写不出好文章。一开始你写的都是废话但你还认为自己写得很好，然后你会逐渐写得越来越好的。这就是为什么我说最有价值的特质之一是坚持不懈。——奥克塔维娅·E·巴特勒（Octavia E. Butler）

就像其它技能一样，当你坚持写作时，你的写作能力就会变得越来越好。争取每个月至少写一篇文章，如果你坚持不懈，终会惊喜发现自己的写作技巧有了提高。

作为一名技术文档工程师，如果你想要锻炼你坚持不懈的精神，可以试试这个#1周2篇文章挑战。

什么是 1 周 2 篇文章挑战？

这项挑战的目标是鼓励技术文档工程师确定自己的写作目标，了解写作标准，最重要的是坚持写作。

参与者需要在自己的博客上每周至少发表 2 篇文章，共持续 4 周。如果能做到这一点，你将能在短短一个月内在你的博客上创建并发表 8 篇文章。很有趣，对吧？😉

我看到很多人都在谈论参加这个挑战的好处。我相信它将帮助你开始坚持写作。

为开源项目做贡献

开源项目的文档可以说和软件本身一样重要。因此，如果你是一个技术文档工程师，你就可以在文档方面为项目做出重要贡献，因为人们无法使用他们不了解的东西。

是的，你可能正在为一个项目或开源组织免费工作。但是，开源贡献可以帮助你提高你的写作技巧、扩大你的人际圈子，并帮助你获得开源组织维护者的推荐和介绍。

开源贡献还可以帮助你增加入选谷歌文档之季（Google Season of Docs）项目的机会。

什么是谷歌文档之季？为什么它很重要？

文档之季是由谷歌组织一个年度项目。其目标是连接技术文档工程师和开源组织，促进开源领域中的文档协作和提升。

这项活动非常重要，因为通过开源项目的文档，用户不仅可以理解该项目，还可以为项目做贡献。

在项目期间，入选的技术文档工程师将花费 3-5 个月的时间来构建一套新的文档、改进现有文档的结构、开发一个急需的教程或改进一个开源组织的贡献流程和指南。

这个项目的有趣之处在于，作为技术文档工程师参与开源项目贡献，你可以获得 3000 至 15000 美元的报酬 。你也会有更大的机会加入谷歌的技术写作团队，还有可能在项目结束后被开源组织留用，继续从事技术写作工作。

帮助你开始写作的 6 个技术写作技巧

完成初稿后，注意以下事项：

• 写作时采用一种风格指南 。它可以帮助你有章可循，且遵循最佳写作原则。
• 段落简短，每个段落仅表达一个观点。不要一个段落包含所有观点。
• 写出简短、清晰、准确的句子，因为大繁至简。
• 写完初稿后，假装自己是读者，大声朗读你写的内容。这将帮助你发现那些可以重新措辞的地方。
• 只在你精力集中的时候才编辑初稿。
• 通过咨询主题专家寻求反馈，因为技术文档工程师并不会知道每个主题的所有技术细节。

总结

技术写作仍然是专业工作场所中一项令人羡慕的技能。预计从 2014 年到 2024 年，技术写作需求将至少增长 10%。

写作像许多其它手艺一样，需要多年的实践来打磨。写作最好的地方在于你可以看到自己的进步。如果你努力练习，随着时间的推移，你就能看到你的写作能力比之前有很大的进步。

另外，技术文档工程师有一个很大的好处，那就是成为终身学习者。因为他们需要精通自己所写的任何领域或话题，以便向读者清楚地传达信息。我强烈鼓励你不仅要开始这段旅程，而且要坚持写作。

就写到这儿吧，朋友们！我希望这篇文章对你们有帮助。如果有帮助，可以在推特上关注我，获取更多此类内容。

如果你曾经在 freeCodeCamp专栏上提交（或阅读）过文章，你的文章可能被我（或由志愿者编辑团队的另一位成员）编辑过。

那是2017年的夏天，我响应freeCodeCamp的创始人 Quincy Larson发起的招募，成为了一名志愿者编辑，帮忙社区编辑来自世界各地的开发人员提交的技术文章。

过去的一年半对我来说是一段奇妙的旅程。从我有幸编辑的文章中，我收获颇丰。作为一名前端开发者，我的写作能力也得到了提升。我也被评为2018 freeCodeCamp Top Contributor，并且2018 年我在我的家乡瓦尼日利亚地区创建了开发者社群，它在不到十个月的时间发展到超过550+的活跃成员。

如果你想知道freeCodeCamp对作为一名志愿者的我的生活影响有多大，我将它记录在此。

RunCloud开启了我的新篇章

我一直坚信在科技生态系统中分享和支持知识的传播，RunCloud这个团队也有着同样的理念——这正是我为何加入他们的原因。

因此，2019年的一月开始我加入RunCloud 作为一名全职技术文档工程师、编辑也是非洲大使。RunCloud是一家SaaS初创公司，可帮助你在Digital Ocean、AWS、Google Cloud Platform等云托管服务器上设置、配置、管理和监控你的VPS，尤其适用于PHP和WordPress应用程序。

作为一名技术文档工程师，我将为Runcloub的产品文档提供支持，制作高质量的博客文章，为开发者社群提供培训资源以及编辑文章。

我也将更多在meetups 和技术会议上发言（并支持非洲各地的开发者活动），作为我们公司支持非洲开发者社区的一部分。你可以通过charles@runcloud.io联系我，如果你是一个开发者社区的负责人，我将很乐意讨论并支持你的活动。

我是如何加入RunCloud——从一条推特开始

2018年12月，我决定不写“年度回顾”，即使我对我取得的成就感到开心：我成长为一名开发者和作家，在不到一年的时间里，我建立了一个超过550活跃会员的开发者社群同时举办了8次聚会。

2019年我想要更大的挑战，所以我在推特上发布了我2019年新的决定。后来我删除了这条推特，但我是这样写的：

新年计划：找一份前端开发的工作，技术文档工程师，又或是开发者推广大使（Developer Advocate）。#100DaysOfCode

我从技术社区获得了大力的支持—Raj，RunCloud团队的一员，联系到我说了以一名技术文档工程师加入RunCloud的可能性，正如他们所说，余下的都是历史。

对于freeCodeCamp——谢谢你

我想表达对Quincy Larson、 Abbey、Jesse、Beau Carnes、Toni Shortsleeve 和编辑团队深深的感谢。我们是一小群技术的弄潮儿，和你们所有人一起工作是我人生中最骄傲的时刻之一，我将永远珍惜！

作为回馈freeCodeCamp的一种方式，我正计划一个月度捐款，也将鼓励你加入我一起回馈这个帮助了数百万人免费学习编程的组织，点击这里。

此刻，新的篇章开始了。

你可以点击这儿，也可以在我们的博客了解更多关于RunCloud的信息。

如果你喜欢写作和技术，技术写作可能是一个适合你的职业。如果你喜欢技术，但又不喜欢整天编程，你也可以做这个工作。

如果你喜欢通过教别人学习，为开源项目做贡献并教别人如何做，或者基本上喜欢通过写作以简单的方式解释复杂的概念，技术写作也可能适合你。

让我们深入了解基本原理，了解在开始技术写作时你应该知道和考虑什么。

目录

在这篇文章中，我们将关注：

• 技术写作是什么
• 技术写作的益处
• 作为一个技术作家所必须具备的技能
• 技术写作流程
• 发布文章的平台
• 技术写作课
• 技术写作论坛和社区
• 一些值得关注的技术作家
• 结束语和参考资料

技术写作是什么

技术写作是一门提供以细节为导向的指导的艺术，以帮助用户了解特定的技能或产品。

而技术作家就是写这些说明的人，也就是所谓的技术文档或教程。这可能包括用户手册、在线支持文章或编码员/API开发人员的内部文档。

技术作家的沟通方式是介绍技术信息，使读者能够理解这些信息。

技术写作的益处

技术作家是终身学习者。由于这项工作涉及以简单明了的方式传达复杂的概念，你必须精通你所写的领域，或者愿意学习相关知识。

这很好，因为你每研究和编写一份新的技术文件，你就会成为该领域的专家。

技术写作也让你对用户有更好的同理心。它帮助你更多地关注产品的读者或用户的感受，而不是你的想法。

作为一名技术作家，你也可以通过向组织投稿来赚钱。这里有一些付钱给你为他们写作的组织，像Smashing Magazine、AuthO, Twilio、和 Stack Overflow.

除了这些，你还可以为开源社区做出贡献，并参与付费的开源项目， 像Google Season of Docs 和Outreachy。

你也可以把技术写作作为一个全职职业——很多公司都需要具备这些技能的人。

作为一个技术作家所必须具备的技能

理解英语的正确使用

在你考虑写作之前，有必要对英语的时态、拼写和基本语法有良好的掌握。你的读者不希望读到一篇充斥着不正确的语法和糟糕的选词的文章。

知道如何清楚和简单地解释事情

知道如何实现一个功能，并不一定意味着你能清楚地把这个过程传达给别人。

为了成为一名好老师，你必须有同理心，有能力以适合你的目标受众的方式教授或解释术语。

如果你不能向一个六岁的孩子解释，那么你自己也不了解它。--阿尔伯特·爱因斯坦

具备一定的写作能力

我相信作家是后天培养的，不是天生的。你只能通过实际写作来学习如何写作。

在你将笔放在纸上之前，你可能永远不会知道自己是否有写作能力。只有一种方法可以知道你是否有一些写作技巧，那就是写作。

所以我鼓励你今天开始写作。你可以选择从我在本节中列出的任何平台开始，以伸展你的写作能力。

当然，有一些技术领域的经验也是一个巨大的好处。

技术写作流程

分析和了解谁是你的读者

当你写一篇技术文章时，需要考虑的最大因素是你的目标/预期受众。它应该始终处于你头脑的最先考虑的。

一个好的技术作家是根据读者的情况来写作的。例如，假设你正在写一篇针对初学者的文章，重要的是，不要假设他们已经知道某些概念。

你可以在文章的开头概述任何必要的先决条件。这将确保你的读者在直接进入你的文章之前拥有（或能够获得）他们需要的知识。

你还可以包括有用的资源链接，这样你的读者只需点击一下就能获得他们需要的信息。

为了知道你是为谁写的，你必须尽可能多地收集关于谁将使用该文件的信息。

重要的是要知道你的听众是否有该领域的专业知识，该主题对他们来说是否完全陌生，或者他们是否介于两者之间（有一些了解）。

你的读者也会有他们自己的期望和需求。你必须确定当读者开始阅读文件时，他们在寻找什么，以及他们将从文件中得到什么。

为了了解你的读者，在你开始写作之前，问自己以下问题：

• 谁是我的读者？
• 他们需要什么？
• 他们将在哪里阅读？
• 他们何时阅读？
• 他们为什么要阅读？
• 他们将如何阅读？

这些问题也有助于你思考读者在阅读你的文章时的体验，我们现在会更多地讨论这个问题。

思考用户体验

用户体验在技术文档中与在网络上的任何地方一样重要。

现在你知道了你的听众和他们的需求，请牢记文件本身是如何满足他们的需求的。否则很容易写出忽略读者如何实际使用文档。

在你写作的时候，不断地退后一步，把你当作读者来看待这个文档。问问自己。它是无障碍的吗？你的读者将如何使用它？他们什么时候使用它？它容易浏览吗？

我们的目标是写一份对你的读者有用和可使用的文件。

规划你的文档

牢记你的用户是谁，然后你就可以构思和规划你的文件了。

这个过程包括一些步骤，我们现在就来看看。

对主题进行彻底研究

在规划你的文档时，你必须研究你要写的主题。只要在谷歌上搜索，就有大量的资源供你使用，并从中获得更深的见解。

不要被诱惑去抄袭别人的作品或文章，并把它当作你自己的作品，因为这是剽窃行为。相反，将这些资源作为你工作的参考和想法。

尽可能多地使用谷歌，从研究期刊、书籍或新闻中获取事实和数据，并尽可能多地收集有关你的主题的信息。然后你就可以开始制定大纲了

制定大纲

在扩展你的文档内容之前，先列出大纲，有助于你以更集中的方式写作。它还可以让你组织你的思想，实现你的写作目标。

大纲还可以帮助你确定你希望读者从文件中得到什么。最后，它为完成你的写作确立了一个时间表。

获取相关的图形/图片

有一个大纲非常有助于确定你需要在文档的不同部分嵌入的各种虚拟辅助工具（信息图表、gif、视频、推文）。

而且，如果你把这些相关的图形放在手边，会使你的写作过程更加容易。

用正确的风格写作

最后，你可以开始写作了！如果你已经完成了所有这些步骤，写作应该变得容易得多。但是你仍然需要确保你的写作风格适合技术文件。

写作需要易懂、直接和专业。花哨或情绪化的文字在技术文件中是不受欢迎的。为了帮助你保持这种风格，这里有一些你应该培养的关键特征。

使用主动语态

在你的文章中使用主动语态是个好主意，因为它比被动语态更容易阅读和理解。

主动语态意味着句子的主语是主动执行动词的动作的人。被动语态是指，主语是动词动作的接受者。

下面是一个被动语态的例子：这文档应该被网络开发人员每年阅读六次。

这里有一个主动语态的例子：每个网络开发人员都应该每年读6次这个文档。

谨慎地选词

选词很重要。确保你使用最适合上下文的词。避免过度使用代词，如“它”和“这个”，因为读者可能难以识别它们指的是哪个名词。

还要避免俚语和粗俗的语言——记住你是在为更多的读者写作，他们的性情和文化风俗可能与你不同。

避免过多的专业术语

如果你是你所在领域的专家，很容易使用你熟悉的行话，而没有意识到它可能会让其他读者感到困惑。

你也应该避免使用你以前没有解释过的缩略语。

下面是一个例子：

不清晰：PWAs确实被认为是多平台开发的未来。它们在安卓和iOS上的可用性使它们成为未来的应用程序。

改进版：Progressive Web Applications（PWAs） 是真正的多平台开发的未来。它们在Android和iOS上的可用性使PWAs成为未来的应用程序。

使用通俗易懂的说法

尽量简短说明，以任何读者都能理解的方式来写。 避免使用大量冗长的字。始终尝试以最清晰的方式解释概念和术语。

视觉上的可视化

大量文字是很难阅读的。即使是最清晰的指示也会在视觉效果不佳的文件中消失。

他们说，一张图片胜过千言万语。这在技术写作中也是正确的。

但是，并不是任何图片都值得在技术文件中使用。技术信息可能很难仅仅通过文字来传达。放置得当的图片或图表可以阐明您的解释。

人们也喜欢视觉效果，因此将它们插入正确的位置很有帮助。考虑下面的图片：

首先，这里有一个没有视觉效果的博客片段：

以下是同一博客的一个片段，但有视觉效果：

在你的文章中添加图片，使内容更有亲和力，更容易理解。除了图片，你还可以在必要时使用gif、emoji、embeds（社交媒体、代码）和代码片段。

深思熟虑的格式、模板和图像或图表也会使你的文本对读者更有帮助。你可以查看下面的参考资料，了解@Bolajiayodeji的技术写作模板。

仔细检查

任何类型的好文章都必须没有拼写和语法错误。这些错误可能看起来很明显，但并不总是容易发现它们（尤其是在长篇文件中）。

在点击 "发布 "之前，一定要仔细检查你的拼写（你知道，点你的Is和交叉你的Ts，从英文的角度来讲，I与T，看起来挺近似的，注意拼写错误）。

有许多免费的工具，如Grammarly和Hemingway app，你可以用它们来检查语法和拼写错误。你也可以把你的文章草稿与别人分享，以便在发表前进行校对。

发布文章的平台

既然你已经决定从事技术写作，这里有一些好的平台，你可以开始免费发布技术内容。它们还可以帮助你建立一个有吸引力的作品集，供未来的雇主查看。

Dev.to是一个由成千上万的技术人员组成的社区，作者和读者都可以有意义地参与并分享想法和资源。

Hashnode是我的首选博客平台，它有令人羡慕的福利，如自定义域名映射和互动社区。在这个平台上建立一个博客也很容易和快速。

freeCodeCamp 有一个非常大的社区和受众范围，是一个发表文章的好地方。然而，你需要申请为他们的专栏写作，并提供一些以前写的文章。

你的申请可能被接受或拒绝，但不要灰心。你总是可以在以后变得更好时重新申请，谁知道呢？你可能会被接受。

如果你真的为他们写作，他们会在发表前审查和编辑你的文章，以确保你发表最精炼的文章。他们还将在其社交媒体平台上分享你的文章，以帮助更多的人阅读它们。

Hackernoon 有超过7000名作家，可能是一个伟大的平台，让你开始向社区中每天超过20万的读者发布你的文章。

Hacker Noon为作家提供帮助，在他们的文章在平台上发布之前进行校对，帮助他们避免常见错误。

技术写作课

就像其他领域一样，技术写作也有各种流程、规则、最佳实践等等。

参加技术写作课程将有助于指导你完成你需要学习的每一件事，也可以给你一个重大的信心提升，以启动你的写作之旅。

以下是一些技术写作课程，你可以去看看：

• 谷歌技术写作课程（免费）
• Udemy技术写作课程（收费）
• Hashnode技术写作训练营（免费）

技术写作论坛和社区

独自一人，我们能做的太少，一起努力，我们能做的太多。——海伦 凯勒

成为社区或论坛的一部分，与那些与你有同样激情的人在一起是有益的。你可以从社区中的其他作家那里得到反馈、纠正、提示，甚至学习一些写作风格提示。

这里有一些社区和论坛供你加入：

• Hashnode
• Dev.to
• Technical Writing World
• Technical Writer Forum
• Write the Docs Forum

一些值得关注的技术作家

在我的技术写作历程中，我来到了一些伟大的技术作家身边，他们的写作历程、一致性和风格给我带来了灵感。

这些作家是我仰望的对象，被我视为技术写作的虚拟导师。有时，他们传授的技术写作技巧让我觉得很有帮助，并从中学到了很多。

以下是这些作家中的一些人（他们的twitter账号）：

• Quincy Larson
• Edidiong Asikpo
• Catalin Pit
• Victoria Lo
• Bolaji Ayodeji
• Amruta Ranade
• Chris Bongers
• Colby Fayock

结束语和参考资料

你不需要有技术写作的学位就可以开始发布技术内容。你可以开始在你的个人博客和公共GitHub项目上写作，同时建立你的作品集并获得实践经验。

真的--只要开始写作。

通过为现有的程序或项目创建新的文档来练习。在GitHub上有许多开源项目，你可以查看并添加到他们的文档中。

是否有一个你喜欢使用的应用，但其文档写得很差？写下你自己的，并在网上分享以获得反馈。你也可以在hashnode上快速建立你的博客并开始写作。

你通过写作以及阅读和思考别的写作者如何创作人物和故事来学习写作。如果你不是一个读者，就别想成为一个写作者。- Jean M. Auel

技术作家总是在学习。通过潜心研究新的主题领域和接受外部反馈，一个好的作家永远不会停止磨练自己的技艺。

当然，好的作家也是贪婪的读者。通过回顾深入阅读或频繁使用的文档，你自己的写作肯定会提高。

我非常期待看到你的技术文章！

参考文献

Introduction to Technical Writing‌‌

How to structure a technical article‌‌

Understanding your audience, the why and how

‌‌Technical Writing template

我希望这篇文章对你有帮助。如果是这样，请在Twitter上关注我，并给我反馈！

在这篇文章中，我们将从 freeCodeCamp 博客文章中获取所有标题，以在 Ghost CMS 中制作目录（ToC）。

我最近在 freeCodeCamp 上发表了一篇相当长的文章，需要在文章中添加一个目录。

Colby Fayock 写了一篇关于如何做到这一点的非常好的支持文章。它非常详细地说明了该过程。

你可以查看视频和关于所有详细信息的全面指南：

如何在你的博客文章或文章中添加目录

Colby Fayock 的文章详细说明了你需要目录（ToC）的原因以及如何使用 Ghost 编辑器（用于在 Ghost CMS 中撰写本文的编辑器）创建目录。

问题是，我需要为其添加链接的文章中有 33 个标题。滚动浏览 10,000 字文档以获取标题然后滚动到顶部以将其添加到目录中的想法让我想知道是否有更好的方法来做到这一点！

目录

• JavaScript 来拯救！
• 获取元素属性
• 获取元素 id 和 innerText
• 筛选 localName
• 结论

JavaScript 来拯救！

考虑到这个想法，我快速搜索并找到了一个可以参考的 Stack Overflow 回答，代码如下：

var ids = document.querySelectorAll('[id]');

Array.prototype.forEach.call( ids, function( el, i ) {
  // "el" 是你的元素
  console.log( el.id ); // 打印 ID
});

所以，让我们现在跳转到浏览器并尝试一下。

我现在将在浏览器中查看已发布的帖子并打开开发人员工具。（在 Chrome 和 Edge 中，打开开发工具的快捷键是 F12。）然后我将该示例代码粘贴到控制台并按 Enter，这是输出：

获取元素属性

效果不错，但我也想要标题，因此查看元素属性的一种快速方法是将它们el包括在一些花括号中：

let ids = document.querySelectorAll('[id]');

Array.prototype.forEach.call(ids, (el) => {
  console.log({el});
});

你会注意到我已经对函数进行了一些清理，将内联函数替换为箭头函数，并替换var为let因此语法更时髦。

现在在浏览器中运行该片段会为我提供每个元素的对象：

然后，我现在可以扩展其中一个元素以获取与其相关的所有属性。从这里我想要得到id（我已经知道在哪）以及innerText标题：

获取元素 id 和 innerText

让我们将innerText元素添加到我们正在使用的代码片段中，看看现在是什么样子。代码如下：

let ids = document.querySelectorAll('[id]');

Array.prototype.forEach.call(ids, (el) => {
  console.log(el.id);
  console.log(el.innerText);
});

这是我们从中得到的输出：

好的，干扰信息真的有点多，因为它显示innerText了文档中每个元素的内容，其中包含很多不相关的信息。我们真正感兴趣的是标题和它的 id。

筛选localName

我在文章中使用的所有标题都是h2标题，所以我想要一种过滤方法。所以我需要从本案例中的{el}属性中获取表示h2元素类型的localName

因此，让我们使用一个if函数来查看localName是否包含h2以及是否将其注销。我还将使用模板文字将锚 id #添加到 id 的开头：

let ids = document.querySelectorAll('[id]');

Array.prototype.forEach.call(ids, (el) => {
  if (el.localName.includes(`h2`)) {
    console.log(`#${el.id}`);
    console.log(el.innerText);
  }
});

现在让我们看一下输出：

好看多了！

现在我可以使用该输出开始制作我的 ToC（文章目录）！

结论

我们采用了一个相当扩展的过程，并将其变成了一个便于使用的代码片段，我们可以在每次需要为我们的博客文章创建 ToC （目录）时在浏览器控制台中使用。

就是这样，希望你发现它有用！ 🙏

如果你喜欢这些内容，可以在我的博客 查看，也可以在推特 上关注我。

感谢你在开发者社区中分享你的专业知识和洞察。

freeCodeCamp 专栏将帮助你启发并鼓励全世界的开发者、设计师和数据科学家等专业人才。

freeCodeCamp.org 是访问量最大的技术网站之一，成千上万的读者将在这里通过阅读你的文章而受益。

我们的社交媒体账号拥有很高的关注度，网站的可访问性和 SEO 效果都做得十分出色，同时，我们提供的学习资源严谨而优质，在业内深受认可——这些优势都将为你的文章吸引更多读者。

在这篇写作指南中，我们将提供一些指导建议，帮助你优化自己的文章，扩大影响力。

请不要把 freeCodeCamp 专栏当作一个发布“日常博客”或意识流似的观察性作文的平台。

内容至上，请在你的文章里展示事实、引言、代码片段和可视化数据等等优质内容。

大量数据表明，文章越深入，人们会花越长的时间阅读它，并且越有可能与朋友分享。

如果你围绕某个主题写出的文章少于 500 字，请先尝试对其进行更多研究。通过深入地并拓展研究，你可以向读者传递更多洞察。

人们很忙，所以你必须立即吸引他们的注意。如何吸引呢？你需要为文章取一个有吸引力的标题。

标题是你的教程中唯一的 100% 的人都会读的部分

在开始撰写正文部分之前，你需要花点时间构思一个吸引眼球的标题。然后，你的整篇文章将围绕标题发散与聚拢，以作支撑。

在过去的八年中，我们发现深入的技术教程对我们专栏的读者群——世界各地数以百万计的开发者——来说是最有帮助的。

比如，技术教程可以采用这样的标题：

• "How to fix…"/《如何修复......》
• "How to build…"/《如何构建......》
• “How to [task] with [tool]”/《如何 [采用什么工具] 来 [完成什么任务]》
• "How [something] works"/《如何实现 [XX] 》
• "The [adjective] guide to…"/《关于 [XX] 的 [深度、高效、完整等等形容词] 指南》
• “What exactly is [noun]?”/《[XX] 究竟是什么》
• “Why [something] matters.”/《为什么说 [XX] 很重要》
• "A history of [something]”/《[XX] 历史解读》
• “The [something] Handbook”/《[XX] 手册》（一般是 10,000 字以上的教程）

你也可以在你的标题中加入人们经常搜索的关键词。不要包含太多（“堆叠关键词”并不好），但值得思考的是，人们在搜索什么，会引导他们找到你的文章。

添加封面图片

在你确定了一个清晰的有信息量的标题之后，点击右上角的齿轮，添加一张合适的封面图片。

一些作者为自己的文章设计封面图片。你可以在一些免费网站设计图片，比如 Canva.com。我们可能在 Facebook 或 Twitter 分享你的文章，所以请注意图像宽高比应为 1.91:1，以免分享时图片不能完整显示。

在创建你的封面图片时要记住一些事情：

• 使用对比鲜明的颜色，使图像/文字真正突出。
• 在你的图片中不要包含太多的文字——只要集中在主要的主题/关键词上（因此，例如，不要包含所有这些文字，“如何用 React 构建一个订餐应用程序”，你可以只说 “如何用 React 构建一个应用程序”或“构建一个 React 应用程序”）。
• 一般来说，请记住：对于封面图片来说，通常越简单越好。你想要一个醒目的图像，在较小的设备上容易查看/阅读。
• 你可以用你的封面图片来帮助建立你作为一个写作者的“品牌”。如果你制作出设计一致的图像，人们往往会仅凭封面图像就认出这是你的教程。

如果你没有图片，你可以从 Pexels、Unsplash 或维基百科等网站下载一张不需要署名的图片，保存它，然后上传到 Ghost。

请不要热链接图片。相反，下载任何你想使用的图片，然后把它们拖到 Ghost 的教程中。这样 freeCodeCamp 可以通过我们自己可靠的 CDN 来提供图片（为了更好的性能和可访问性）。请尽量将图片大小控制在 1MB 以内。

同时请记住，使用屏幕阅读器的人将无法看到你的图片、图表和屏幕截图。因此，请在所有对理解你的教程很重要的图片上加上一个简明而相关的标题。这对无障碍性是有帮助的，并允许你指出关于图片的重要的额外信息。

设置 URL

你可以直接设置文章的 URL。我们建议你使用简短的描述性的 URL，比如 “machine-learning-with-pytorch-tutorial” 或 “from-trucker-to-developer”。对，使用英文而不是拼音。

设置好 URL 并发布文章之后，请不要更改 URL，因为有可能我们在别处推荐了你的文章，URL 变了的话就会导致 404 错误。

添加标签

你可以为你的文章选择一到五个标签。当你键入一些关键词时，下拉列表会出现标签提示，从中选择即可（中文版标签即将上线）。

你可以为你的教程选择一到五个标签。请告诉编辑团队你选择了哪些标签，我们会为你添加。

这些标签将使读者通过搜索和浏览标签时更容易发现你的教程。

你选择的第一个标签是最重要的，它会显示在你的文章上方，如下所示：

请不要更改菜单中的任何元信息。我们的专栏对这些有合理的默认值。

如何写出人们乐于阅读的文章

重视语法，拼写和格式

条理严谨且格式清晰的文章阅读起来令人愉悦。以下建议可以帮助提高你的文章的可读性：

• 简单化：尽可能使用简单直接的语句。
• 使用短句：将长句分解为短句，这有助于人们更快地阅读并更好地理解。
• 使用短段落：将较长的段落分解为一两句的段落。如果你的文章有好多长段落，读者可能放弃阅读或只是略读。
• 检查标点符号：太多感叹号可能会分散注意力！少用分号；只需使用句号。省略号......好吧......看起来有点累赘。
• 使用小标题让文章结构更清晰：我们的专栏为你提供了大大小小的标题。对主要的主题使用大标题，而对这些主题中的部分使用小的副标题。你可以用 Markdown 语法添加标题（## 代表 H2，### 代表 H3，以此类推），或者双击你想用来做标题的文本。下面的菜单会出现。

• 不要使用过多的粗体、斜体或两者：太多的文字格式会使人难以阅读。特别是如果你同时使用粗体和斜体。分别使用黑体和斜体，而且要少用。
• 尽量少使用缩写：有的缩写并不是所有人（特别是初学者）都知道，比如，LGTM（look good to me），e.g.（例如），js（JavaScript），所以少使用缩写吧。
• 特别注意全角/半角文字内容和标点符号的用法，比如，全角文字和半角文字之间需要加空格（为下列项目添加 CSS 属性）。

尽可能地使用主动语态

人们通常在谈话中自然地使用主动语态。它更随意，更平易近人，并意味着行动和权威。

因此，在你的教程中尽可能使用主动语态。

下面是一个主动语态的例子：

“你可以按照这些步骤来安装Node.js。”

下面是一个被动语态的例子：

“Node.js 可以按照这些步骤被安装。”

这看起来很微妙，但主动语态的例子更容易与读者联系起来，帮助他们自信地遵循指南。

有时，把写教程想成是在向朋友解释什么，会有帮助。你不需要使用过于复杂的语言，你会表现得友好而有礼貌，而且事情会合乎逻辑。

反复校对

有些作者写得很快，他们可以一边思考一边将自己的想法写下来。有些作者会在做好所有研究之后才开始写作。

无论你习惯什么样的写作过程，请在写好之后跳出作者思维，从一个陌生的读者的视角来阅读你的文章。

反复阅读，甚至可以读出声来。然后你会惊讶地发现其中有一些标点错误、用词错误或者不通顺的语句。

在代码中添加语法高亮显示

你可以通过键入三个反引号（```），然后按空格键，来创建代码块。

你甚至可以指定要进行语法突出显示的编程语言，例如，输入```js 将高亮显示 JavaScript 语法。我们还支持其他常用的十几种编程语言的语法高亮显示。

紧扣主题

读者的时间是宝贵的。尽量让你的文章值得他们从忙碌的生活中抽出来阅读，也就是说帮助他们尽可能多地从你的文章中获取价值。

尽可能按照这个步骤来撰写深度技术文章：

1、写一个简明介绍，告诉读者他们将从这篇文章看到什么

2、使用像这样的编号列表来展示步骤

3、尽可能详细阐述

4、最后提醒读者他们看了什么内容

写一篇完整的长文，而不是把长文分为多篇短文

我们从长期的观察中发现，如果人们没有阅读一个系列文章的前面部分的话，那么他们没有什么耐心阅读其中的第二、第三或第 n 部分。

与此同时，我们发现那些非常长的、有深度的文章却能收到非常好的反响。人们会把你的长文添加书签或在社交媒体上分享，以便他们可以随时回过头来再阅读。

如果一篇文章比较长，通常人们会认为这篇文章是作者认真写的，内容是丰富的。这会鼓励读者放慢脚步，真正花时间阅读你的文章。许多读者甚至会在家里打开他们的代码编辑器，边阅读边写代码。

文章内容必须符合规定

freeCodeCamp 的学员中既有成年人也有青少年，所以，你在这里发布的文章不得包含黄、赌、毒等不良信息或政治敏感内容，避免文章中出现侮辱性语言。

如果某篇文章违反了 freeCodeCamp 的行为准则，我们会立即将其删除。但我们会保存一份副本，并发给你，供你自己记录，这样你就不会丢失你的内容。

使用无需署名的图像或你自己创造的图像

你可以使用屏幕截图和其他你自己创建的图片。但是，如果你不拥有某张图片的版权，可以使用无需署名的类似图片来代替。这些图片不需要授权费或署名。

同样，如果你需要一个图片库，你可以在一些网站上找到这些图片，如 Pexels、Unsplash 和维基百科。

提醒一下，请不要热链接图片。相反，请下载任何你想在你的教程中使用的图片，然后将它们拖入 Ghost。这样 freeCodeCamp 可以通过我们自己可靠的 CDN 来提供图片（为了更好的性能和可访问性）。请尽量将图片大小控制在 1MB 以内。

有些图片——如网络漫画——是以分享为目的的。对于这些，你可以插入图片，然后注明“图片来源：XKCD”，并附上网络漫画的具体页面的链接。

始终注明来源，不要抄袭

抄袭是指某人将别人的文章（或图像或代码等）误当作是自己的。这是一种严重的错误行为，会导致人们被解雇和被踢出学校。在 freeCodeCamp 的专栏上，我们也同样严肃地对待它。

很少有人不顾尊严地试图在 freeCodeCamp 的专栏上抄袭。但在过去的 7 年中，有几个人是这样的。我们已经发现了他们，删除了他们的教程，并终身禁止他们进入我们的社区。

不要担心——你不会意外地剽窃任何东西。抄袭是一种故意的行为。

如何正确列出你的资料来源

如果你转述（或直接引用）某人在其他教程、视频、课程或其他媒介中说过的话，你应该归功于他们。这意味着要添加一个原始来源的链接，并使用引文格式，比如这样：

"This game is controlled entirely by typing into a command line interface. Because the game is real-time in nature, this can lead to some intense moments of rapidly typing commands as you try to save your drones from danger." (来源：Quincy Larson)

这包括从官方文档、StackOverflow、GitHub 和所有类似资源中提取的文本（或代码）。如果你从这样的来源复制和粘贴东西，确保你注明引用它并链接到它。

始终将引文归于最初说这些话的人。如果是多行引语，你可以使用像这样的引语来分割长的段落。

“When you have wit of your own, it’s a pleasure to

credit other people for theirs.”
― Criss Jami

如果你的代码在很大程度上受到了别人的启发（或借用了别人的代码），你应该归功于他们。

在你发表严重依赖他人创作的教程之前，请问自己：我的教程是否对该人的工作进行了实质性的扩展？如果不是，它可能不值得成为教程。

关于使用别人的文字的最后说明：在可以的情况下，使用自己的文字总是更好。因此，与其过多地复制/粘贴和引用其他来源的信息，不如试着消化信息，用你自己的话来解释它。这将有助于你更好地理解它，而且你不会有剽窃他人作品的风险。

但如果你必须引用或借用其他来源的资料，请确保正确引用。

抄袭的一些例子

这里有几个抄袭的例子——即，不应该做什么。第一个例子应该相当清楚（它是一字不差地复制的）。

原文：

Just a quick note before we get started: Instagram's desktop interface and mobile app are quite different. Most people use Instagram on their mobile device (from the Instagram app) because that's where you can actually post photos. (Source: Abbey Rennemeyer)

抄袭的文字：

Ok, everyone ready to learn about Instagram? Let's dive in!

Just a quick note before we get started: Instagram's desktop interface and mobile app are quite different. Most people use Instagram on their mobile device (from the Instagram app) because that's where you can actually post photos.

Now that we have that out of the way, we're ready to go.

正如你所看到的，抄袭的文字被夹在原创文字之间。添加别人制作得非常好的短语或段落是很诱人的。但除非你注明引用这些部分，否则就是抄袭。

下面的第二个例子，可能没有那么突出。但如果你仔细地转述了别人的话，这仍然是抄袭行为。

原文：

There are many reasons you might want to share photos and videos on Instagram.

Perhaps you're starting a business or launching a product. You might work for a company that wants to have an Instagram presence. Maybe you want to build your personal brand as a photographer, traveler, or artist. Or you just want to share what you're into right now via pictures.

Whatever the reason, Instagram is a great place to share ideas, messaging, and art online. (Source)

抄袭的文字：

There are lots of reasons to share photos and videos on Insta.

Maybe you're starting your own business or launching some product. Maybe you work for an organization who wants to have an Instagram presence. Or maybe you want to create your own brand. Or you just want to show what you're doing now in pictures.

Either way, Instagram is a great place to post those ideas, messages, and art online.

正如你所看到的，上面的文字在很大程度上是基于原文的。它可能改变了几个字，或遗漏了几个字，但很明显，这个人并不是自己写的。同样，这也是不行的，会被认为是抄袭。

如果你对什么是抄袭有任何疑问，请做一些研究，确保你知道如何正确引用你的来源和创造原创作品。

关于多平台交叉发布文章的说明

如果你希望有很多人阅读你的文章，那么我们建议你不要在多个平台发布文章，而是专注在一个专栏写作——不管是 freeCodeCamp 的专栏，还是你自己的博客，或是其他线上平台。

这方面有几个例外：

• 在像 LinkedIn 这样的不被谷歌索引的平台中交叉发布教程是值得的。
• 如果你想在自己的博客上发表你在其他专栏上写的文章，让潜在的雇主看到，你可以在自己的博客上交叉发布，只需使用一个规范的 URL 来指向原始专栏。这将减少谷歌感到困惑并在其结果中显示错误版本的可能性。

你可以将自己之前写的关于某个主题的几篇文章（例如 “Visual Studios 插件”或“高级 Bash 命令”）汇集成一篇较长的文章，在 freeCodeCamp 专栏发布。

我们的理念是，因为我们要花几个小时辅导你编写教程，精心编辑，并向更广大的 freeCodeCamp 社区宣传，我们要求你不要在 Medium 等开放发布网站上交叉发布文章。

文章中是否可以出现推广性质的内容

freeCodeCamp.org 是靠捐款人支持的公益组织。我们不希望让任何人感觉我们有所谓的“收费策略”（我们完全没有），否则可能会影响人们给我们捐款的意愿。

不过，我们完全理解你可能希望宣传自己的最新书籍、课程、SaaS 应用程序或让人们注册你的邮件列表或在社交媒体上关注你。

我们希望你尽可能优雅地做推广，比如，你完全可以在文章末尾用一句话介绍你的产品。

不要在文章开头就放你的产品链接，因为这看起来就是垃圾信息。不要在你的教程中使用促销链接，除非它们是你亲自创建的书籍或课程的链接。

另外，请注意，我们不允许注册品牌账号，禁止任何形式的代写。而且我们不会将教程作者从公司的一个员工改为另一个员工。

请不要使用你的作者账号代表尚未获得邀请注册成为 freeCodeCamp 专栏作者的人发布文章。

请注意，对于你自己的站点的 SEO——与大多数热门网站不同——freeCodeCamp 专栏的所有链接都是 rel =“doFollow”，意思是你在文章中链接的每个页面（包括你自己的博客）都会在 Google 排名中获得提升。请谨慎加入链接，不能添加过多。

正式发布

当你确定你的文章已经准备好分享给读者，你可以将草稿链接发送给 chinese@freecodecamp.org。我们的编辑团队将尽快帮助你检查、优化文章，然后正式发布。

我们主要会看标题和开头段落是否可以优化，同时也会更正文章中的格式问题或语法错误。

如果我们觉得你的文章要改的内容比较多，我们会告诉你，那么你可以修改之后重新提交。

最后，一个重要的说明：如果有公司付钱给你写文章，然后试图在 freeCodeCamp 社区专栏上发表，请在提交草稿时告知编辑团队。

其他建议

GitHub Markdown

在这里你可以使用 GitHub 风格的 Markdown 撰写文章。

你可以直接将 Markdown 内容粘贴到编辑框中，内容会立即转换为富文本格式。

你也可以在文章中键入 Markdown 语法来指定格式，比如，用＃或 ## 编写标题，或者键入 * 表示项目符号列表。

轻松嵌入

如果你想嵌入 Twitter、YouTube 的内容，只需单击新行开头的 + 图标，即可从各种嵌入工具中进行选择。

不过，我们鼓励你谨慎嵌入内容，原因有三：

• 嵌入内容将调用外部服务，可能会使访问速度变慢。
• 很多人使用屏幕阅读器阅读文章。开发者社区中有相当大比例的人们存在视力障碍（或完全失明），嵌入内容的可访问性不如文本的可访问性好。
• 专栏的每篇教程都有一个加速移动页面的版本，嵌入的内容在那里可能无法正常显示出来。

尽可能使用“你”而不是“我们”

有时，在编写教程时，作者会忍不住使用“我们”：“现在我们需要安装 Node.js......”。这是一种自然的交流方式。

但我们发现，使用第二人称（“你”）会更有效。它让人感觉你是在直接对读者说话，并让读者在学习你的指南时有代入感。

当然，也有例外——例如，我们在本风格指南中经常使用“我们”。:) 但是，请使用你最好的判断，在适当的时候尽量使用“你”。

如果你还没有一个 freeCodeCamp 专栏贡献者账号，你可以填写这份表单来申请。

再次感谢你在开发者社区中分享知识

我们希望这份指南能帮助你写出更好的教程，以便整个社区都能从你的洞察中受益。

Happy coding.

-  freeCodeCamp 编辑团队