最近，我写完了我的第一本技术类书籍——是的，我终于写完了。

写书这件事已经躺在我的待办事项清单里很久了。现在我终于把它完成了，想要跟大家分享一下我的经验。

在这篇帖子里，我会尽量记录我的整个写作历程。所有我都会谈到，包括我的动机、遇到的难关以及用到的工具、技术和资源。

我的书重点讲的是Hyperledger Composer区块链工具。这本书是完全免费的，目前仅支持PDF格式。

帖子里提到的所有要点也同样有助于技术博客写作。所以，咱们开始吧，一起深入了解我到底学到了什么。

动机

从2018年年底我就开始写技术文章和教程了。到现在，我已经对写文章或教程的流程得心应手了。我知道自己该如何写好一篇文章，以及应该使用哪种工具来写作。

但，如果说到写一本书—尤其是技术书—这是很不同以往的。

我写这本书的动机是好奇心。我想知道那些作者是如何写书的。他们的思考过程是怎样的？他们会用到什么工具？当然，我还想知道写一本书是什么样的体验？？

我是一名软件工程师，从2018年起我就一直从事区块链相关工作。我了解过不同的区块链，比如Ethereum和Hyperledger Fabric。我也用过很多工具，比如truffle、remix和hyperledger composer。

有好多不同的东西我都想写，像Ethereum或者Hyperledger Fabric。

但因为这是我的第一本书，这些主题对我来说都不太适合。它们会占据我过多的时间和精力。所以，我选择了一个简单的主题：Hyperledger Composer。

第一道难关

在开始之前，我犹豫该用哪种工具或编辑器来写书。

我应该用Word、Google Docs还是其它什么工具呢？
主要的问题是如何正确排版代码片段。这些编辑器都不是为技术写作设计的。

有不同的添加代码方法，但那需要额外的排版工作。

我读了很多关于有哪些技术书籍写作工具好用的文章。我试用了很多工具，但都没有让我满意的。我浪费了很多时间去寻找完美的工具。

最后，我意识到，编辑器只是让写作过程更简便，让书籍管理更简化。但真正重要的是内容。所以，我不再寻找完美的编辑器，而是转向了基础的工具。

基础工具：VS Code

我用我最喜欢的代码编辑器来写书。是的，VS Code。

我花了几天时间在网上搜索，没有一篇文章建议说你需要任何特定的工具或编辑器来写技术书籍。VS Code或者Atom就足够了。

我在VS Code里用我最喜欢的Markdown格式写完了整本书。为了让写作更容易，我用到了一些Markdown插件，比如：Markdown All in One和Markdown Preview Enhanced。

第一个插件帮助写作，第二个插件帮助预览。可以看到Markdown转换为HTML或其它格式后是什么样子，以及会有什么变化。

Markdown All in One也有预览模式，但Markdown Preview Enhanced有多个主题和选项，可以将Markdown文件以HTML、PDF和其它可读格式如epub或Mobi导出。

提醒一下—想导出其它文档格式需要你在电脑上安装Pandoc。

我是Windows系统用户，对于Mac系统用户，我发现还可以选择很多很棒的编辑器，比如bear和ulysses等等。

最近，我发现了很多在Windows系统和MacOS系统都能用来写书的Markdown编辑器。搜一搜Notion、Typora、iA Writer和SimpleNote。

划重点：不要浪费太多时间去寻找完美的编辑器。选择了一款编辑器就开始写作。慢慢你就会懂得的。

第二道难关

然后，我开始问自己，我应该从哪儿开始写呢？我应该怎么写呢？我应该怎么做呢？

简而言之，我想知道我到底该如何写这本书，这样读者就能从书中得到最大的收获。

这些问题让我抓耳挠腮了很久。一开始，我改了有4、5次办法。

在这一点上，我的建议是花一点时间真正思考你的方法。因为一旦你写到中途，想要做更改就不容易了。

问问题

关于这本书，我问了自己这些问题，并记下了我的想法。

1. 我的目标读者是谁？他们是小白、中级选手还是大神？
2. 他们需要一些主题背景知识吗？
3. 我该如何组织这本书？
4. 我该如何为文件或者章节命名，便于查找每个主题？
5. 我该如何跟踪自己的进展？
6. 我该如何维护书中各章节和草稿的版本？很多时候，上一版内容其实比当前版本好得多。

以上就是我问自己的一些基本问题，这些问题很有用。

我的方法

现在我要讲讲我在写这本书时用到的方法。

创建一个待办事项清单（to-do list）

首先，我建了一个待办事项清单。在清单上我记下了所有的要点、主题、副主题、参考文献、序言、封面、书名等等。

我把所有想到的关于这本书的想法都尽可能加到清单里。

我建议创建2份同样的待办事项清单：一份纸质档，一份电子档。

首先，在纸上记下所有要点。所有内容都记下后，再阅读2至3遍。然后，不管脑子里闪现什么新的点子，都记到纸上。

例如，如果你想到了将如何解释某个特殊的主题，就把想法记下来。这会让你的写作变得更容易。后面在你开始写这个主题时，你就可以参考这些笔记。

有了纸质版待办事项清单后，你就再创建一个电子版，并按时间顺序保存所有要点。

这就是我以前做的待办事项 清单：

任务

• [x] 索引
• [x] 封面
• [x] 标题
• [x] 副标题
• [x] 前言
• [x] 什么是Blockchain和Hyperledger Fabric？
• [x] 介绍Hyperledger Composer
• [x] 环境要求和设置
  • [x] Azure
  • [x] AWS
  • [x] GCP
• [x] 项目目标
• [x] Composer中的项目设置
• [x] 模型文件
  • [x] 定义
  • [x] 建模语言
  • [x] 项目代码
• [x] 脚本文件
  • [x] 定义
  • [x] 语法
  • [x] 项目代码
• [x] 查询文件
  • [x] 定义
  • [x] 查询语言
  • [x] 项目代码
• [x] ACL文件
  • [x] 定义
  • [x] 语法
  • [x] 项目代码
• [x] 在Composer Playground中部署
• [x] 在Composer Playground中测试
• [x] 导出.bna
• [x] Composer Rest服务器
• [x] 前端
• [x] 总结
• [x] 参考文献
• [x] 关于我
• [x] 一查语法
• [x] 复查语法
• [x] 阅读草稿
• [x] 阅读最后的草稿
• [x] PDF格式
• [x] 在PDF中添加页码
• [x] 新章节另起一页
• [x] 感谢信
• [x] 许可协议
• [x] 封底

我是用的Markdown格式写的待办事项你可以选择任何自己觉得最方便的格式来写。

从小处着手，但一定要开始

记住，你不必按顺序写每个主题。有很多主题可能要依赖于之前的主题，但其余主题并不依赖。

另外，你也不必一次性写完所有主题。哪个主题你觉得写来顺畅，就从哪个主题开始写。

你的目标应该是开始行动起来写书。计划在几周内写10%-20%的量。一旦开始了，就会有声音不断提醒你，你必须写完这本书。久而久之，你就会发现，这变成了一个巨大的动力。

如果主题不熟悉，不用担心。尽管去互联网上寻求帮助。读一读别人是怎么阐述的，从中获得灵感，然后用你自己的方式写出来。

请记住—如果你要使用他人作品中的任何内容，一定要通知原作者。在你的书里做适当引用，并在最后的参考文献中，列出原作者的作品。

将此视为一种专业的礼节。--约翰威克？

编排顺序

我花了一段时间才懂得文件命名规范的重要性。

最开始，每个主题我都用 第一章、第二章 这种命名规范来命名。结果发现这种方式很糟糕。

这种命名方案的问题是你必须维护一个单独的说明性文件。或者你必须打开每个文件来确认里面写的是什么。

另一个问题是如果你在章节之间新增了一个章节，你就不得不给后面所有的章节重新命名。

我发现了2种有用的命名规范，但也各有缺点。

一种选择是使用章节编号-主题：文件命名为一个章节编号跟上该章节的主题。比如这样第10章-区块链介绍。

章节编号用2位数。这有助于在不同文件中为同一章节增加子章节。比如这样第11章-区块链的历史。

这种命名方式的另一个好处是它将按你书籍章节的顺序显示所有文件。

缺点： 在章节之间新增一个章节时，你需要给后面所有的章节重新命名。

第二个选择是使用文件名作为主题：将所有文件以主题名命名。这样你可以按任意顺序写主题。而且你可以保持书中的顺序与你待办事项清单中的顺序一致。

缺点： 所有文件都将按字母顺序排列。文件数达10至15个之后，就会变得难以追踪所有文件，而且也更难将这些文件组合在一起形成草稿。

最后，我选择了第二种方式。对我来说还效果还不错。

为了创建草稿，我创建了一个Node.js脚本。在这个脚本里，我将所有主题输入一个数组中。然后我创建了一个草稿文件，并在其中追加了所有主题。当然，要先通过阅读主题？。作为一名软件工程师的一些优势？

这个脚本是我编辑时的一个救星。很多次，我都是在脚本里更新主题或图片，以及修改语法错误。这里要说Grammarly（译者注：Grammarly是一种在线语法纠正和校对工具）真的拯救了我……但并没能完全拯救，因为我用的是免费版。？

书籍之旅记录

写书不是一场短跑赛，而是一场马拉松。每当写完一个主题或完成当日写作时，总要记得保存。

第二天，你可能会对已完成的同一主题产生新的想法。你可能会花上一个小时都不能得到满意结果。这个时候，好的做法是撤销还原（UNDO）。但编辑器也有撤销次数极限（不同的编辑器极限各有不同）。 不要过多测试它的极限。

我用Git来做版本控制，而不是依赖编辑器或制作重复的副本。不要以为Git只能用来管理代码。它是一个多功能的工具，它的可应用范围超乎你的想象。

对于不知道Git是什么的读者可看以下释义：

Git是一个分布式版本控制系统，用于记录软件开发过程中的源码变更。Git为程序员之间协同工作而设计，但也能用于记录所有文件变更。--维基百科

你不必等学完Git的一切才开始用它来写作。掌握基础的命令，如init、add、commit、logs和checkout就远远足够你维护文档版本以及保证文本的可访问性和安全性了。

可用的Git代码托管平台有很多，比如：GitHub和GitLab 等。要将你的书籍托管在这些平台上，可采用以下步骤：

1. 创建一个账号。我个人选择的是用GitHub平台。
2. 创建一个私人仓库，保持默认选项。你可以在将来把这个仓库可见性设置为公共。
3. 仓库创建完毕后，根据提示进行操作。基本上，这一步是将你本地Git连接到你的托管仓库。
4. 再学习2条命令：push和pull。push命令是将本地变更上传至云仓库，pull命令是从云端获取内容。

之后，无论何时你做任何变更，只需add、commit和push3条命令搞定。是不是很简单？？

提交几次之后，你就会对Git运用自如了。

阅读这篇精彩文章一小时掌握Git和版本控制，学习更多Git知识。

我用到的工具和资源

在写作、编辑、排版和设计这本书时，我用过许多工具和资源。

写作

对于写作，如我前文所述，我用的是VS Code编辑器和几个Markdown插件。

表情符号，我用的是复制粘贴emojis。

编辑

我用的是免费版Grammarly来纠正语法错误。免费版可以纠正所有的基础错误，比如错误的或遗漏的冠词、介词、逗号等等。

我用的是在线PDF编辑器 给书籍添加页码。

排版

在VS Code中，我用Preview插件将Markdown生成PDF格式。我用的是默认的Git Markdown样式，你也可以在设置里更改样式。

PDF中的分页符

因为我是用Markdown格式进行写作的，在输出为PDF格式时会产生差异。比如，新建的主题是接着上一页排版的，而没有另起一页。

为解决这个问题，我在每个主题最后都使用了用于分页的HTML代码。

<div style="page-break-after:always;"></div>

这个代码可以让其后的内容另起一页。
你也可以添加页面序列的结尾，像这样*****。

<div style="page-break-after:always; display:block; text-align:center; border:none">*****</div>

关于我的页面

在我的书中 关于我部分，我把内容分为了两栏：一栏是关于我的简介，另一栏是一张个人照片。

我花了一段时间才了解Markdown格式的全部功能。我们可以在Markdown里添加原生html代码。下面是我的“关于我”页面的内容：

<div >
  <img align="right" style="padding-left:65px" src="../images/profilepic.JPEG" width="400px" height="450px" />
</div>

Hello, I am **_Shubham Kumar Chadokar_**.

I am a Software Engineer and in my short career of almost 4 years, I've had the opportunity to work on Blockchain, Nodejs, Golang, and Docker.

I've learned about other tech as well, but these are my primary focus. I love to write articles and tutorials on new tech by following a hands-on approach. This is my first book.

Front end development isn't my specialty, and that's why I didn't include it in the book.

If you have any queries or questions, please feel free to drop me an email.

:e-mail: [hello@schadokar.dev](hello@schadokar.dev)
:globe_with_meridians: [schadokar.dev](https://schadokar.dev)
<img src="https://github.githubassets.com/images/icons/emoji/octocat.png" style="width:20px;" />[github.com/schadokar](https://github.com/schadokar)

对于Octocat（译者注：GitHub的吉祥物章鱼猫），我用的是img标签。

看起来像这样。

感谢页

我添加了一个感谢页，以此感谢Hyperledger Composer社区的工作付出。我试着将内容加在页面中间位置。

<div style="padding-top:40%; text-align: center; font-size:35px;">
Thank You <img src="https://emojipedia-us.s3.dualstack.us-west-1.amazonaws.com/thumbs/240/microsoft/209/person-with-folded-hands_1f64f.png" style="width:40px" />
</div>
<div style="text-align: center; font-size:25px;">
I especially want to thanks the entire
<a href="https://github.com/hyperledger/composer/graphs/contributors">Hyperledger Composer Community</a> for creating such
an amazing tool. Many developers entered into the blockchain domain because of the simplicity of the composer. <br />
It is unfortunate that it is deprecated but it sets a great example of easy automation,
wrapping a complex Hyperledger Fabric into the easy to use Hyperledger Composer.
</div>

看起来像这样。

书的标题和副标题

书的标题应该用几个词或一个短句就表明书的内容。

在写书的时候，记下你使用的所有关键词。这将有助于你想出一个好标题。你要抓住这本书的本质，并让读者也知道，例如，它是偏理论性的还是偏实践性的。

副标题应该向读者提供更多细节，让读者知道自己将从书中获得什么或者他们即将学到什么。

副标题用一句话是合适的，不应超过两句。不要过长—让读者自己阅读书里的内容。副标题的目的是让读者通过一句话了解整本书的格调，但仍觉语意未尽？。

我的书的标题是 《玩转Hyperledger Composer》，副标题是 《使用Hyperledger Composer在区块链中创建一个供应链管理项目》。

在开始写书时，不要花太多时间在书的标题上。当你写完了，你能站在一个更好的视角去想标题。所有内容都写完了，你知道写了些什么，读者能从中收获什么。

就我而言，我在书籍出版前的最后一秒更改了书的标题和封面。在这之前，它是如此的无聊？。

设计书籍封面

你可能听说过习语不要以封面评价一本书（不要以貌取人）。
但残酷的现实是，一本书的封面非常重要。它是一本书的脸。

封面尽量保持简单且信息翔实。不要过度设计。一个简单的标题和一个简短的副标题加上一两张图片就足够了。

我开始设计书的封面时，参考了其他书，并试着Paint中进行编辑。结果完全是一场灾难，我想不出什么好的设计了。

然后我意识到，设计不是我的长处。我决定找一个自由职业者来做这件事，所以我查看了UpWork和Fiverr等自由职业网站。

然后，我发现了Canva。这真是一个很棒的工具。太神奇了！

Canva是一个图形设计平台，支持用户创建社交媒体图形、演示文稿、海报和其他视觉内容。它可以在网页端和移动端使用，并集成了数百万张图片、字体、模板和插图。维基百科

我通过Canva上书籍封面版块中的一个模板，创建了我的书籍封面。还不错吧？

许可协议

我写这本书是出于好奇心和乐趣。所以，我希望它是免费的，而且是开源的，但我不希望有人利用这本书来谋利。没有许可协议，就没有约束。

我搜索了一段时间，在StackOverflow上发现了一个关于免费许可协议的很好回答，即知识共享版权许可协议（Creative Commons Licenses）。

知识共享基金会（Creative Commons）是一个非营利组织，帮助解决知识分享和创造力有关的法律困境，应对世界上版权方面的挑战。

他们会提供一个表格，表格上面会问几个与你想要申请的许可协议类型相关的问题。填写表格，然后就可以了，你的许可证就准备好了。你可以复制粘贴或通过嵌入的链接获得许可证。

出版你的书

可选的书籍出版方式有很多。你可以找一家出版社，把你的草稿送过去。如果他们想出版，你就可以着手处理然后与其达成协议。

达成协议后，出版社负责其它过程，比如书籍的排版和编辑、吸引人的书籍封面设计、所有的协议许可、出版过程，以及最重要的市场营销。

简而言之，如果你想通过你的书获得稿费，而且你期待一个好的收益，那么出版社是最佳选择。

另一个选择是自助出版。是的，我们可以自行出版自己的书。亚马逊的自行出版系统Kindle Direct Publishing（KDP）提供了一个很好的平台。它是免费的，而且可以在全世界范围内出版书籍。

你将从每笔销售中获得70%的利润。KDP负责所有的出版过程。你只需将书籍写好、上传并排版。

你只需填写你想收取的价格，以及你的书和你自己的一些基本信息。你可以阅读他们的教程了解更多信息—他们的教程写得非常棒。

但我希望我的书是免费的，而且我没有耐心操作上述过程。所以，我并没有依靠任何第三方就自行出版了我的书。

我只是把书转换成PDF格式，并把它存在AWS S3 Bucket上，这样任何人都可以下载。然后我把这本书托管在我的网站上。简单吧？

分享你的作品

完成你的杰作后，就该向世界展示它了。
如果你没有与出版商合作，或者即使你有，你也必须推广自己的作品。

这些是我使用的几个平台，但你不必局限于这几个。

领英（LinkdeIn）

LinkedIn是一个专业平台，上面有许多技术领域不同专业的开发人员。凡是你能说得出来的职业，在LinkedIn上你也都能找到从事该职业的人。

与他们分享你的作品，并询问反馈。90%的可能你都会得到回复。我向Dan Selmon分享了我的书，他是Hyperledger Composer的一名贡献者。还有Srinivas Mahankali，他写了很多关于区块链的书。

他们都非常乐于助人，并给出了他们真诚的反馈。我很感谢Dan，他甚至提出会在他的社交网络LinkedIn和Twitter上分享我的书。

Reddit

Reddit是一个社区枢纽。你会发现这里有许多关于各种主题的活跃社区。你只需加入与你工作相关的社区，然后在那里分享你的作品。

你会发现Reddit上有很多活跃的成员，在这些群体中，他们并不羞于分享自己的观点。如果你的作品有提升空间，他们中的一些人可能会提供帮助。

但在分享你的作品之前，请务必阅读指南。如果你违反了其中任何一条规则，他们将删除你的帖子。

推特（Twitter）

推特不仅仅是一个人们分享自己观点的社交平台。所以不要低估它。

如果你喜欢事实和数字，可以看到：Twitter上有13亿多个账户，3.3亿月活跃用户，1.52亿日活跃用户，每天有5亿条推文。这个数字是很庞大的。

你只需要在有限的280个字符内，精心设计你的信息，选择合适的关键词，你就有可能接触到大量的受众。

博客

做一些研究，弄清楚哪些出版物或电子杂志会发布你图书类别的文章。与他们分享你的书中摘要和细节。

询问他们是否可以写一篇关于你的书籍的文章。或者你可以写一篇关于你的书的文章，然后把文章初稿发给他们。

还有很多其它的平台你也可以试一试————只要你去深入了解一下。

总结

这就是我第一次写书的经历。写书花了一些时间，但是值得的。现在，我的作品集上又多了一个徽章。

我从这次经历中学到了很多东西。这篇文章可以作为我所有学习的记录，供任何想写第一本书或下一本书的人参考。

下面是到目前为止我用过的工具最终清单。

若有我未列出的工具，也欢迎你推荐。

谢谢你的阅读，别忘了与我分享你的第一本书。

我所使用工具的最终清单

• 编辑器：Visual Studio Code及2个Markdown插件
• 版本控制工具：Git和GitHub
• 表情符号：复制粘贴emojis
• 语法检查：Grammarly
• 许可协议：Creative Commons Licenses
• 封面设计：Canva
• PDF页码编辑器：在线PDF编辑器
• 电子书存储：AWS S3 bucket
• 书籍托管：我的博客

感谢阅读

如果你有任何反馈或建议帮助我改进这篇文章，请在推特上与我联系或给我发电子邮件。

• 阅读我的其它文章
• 订阅我的简报

封面照片：来自Unsplash，作者 Thought Catalog

可能想到开源贡献，你就会觉得畏惧，尤其是如果你之前从未参与过开源贡献，或者你习惯的是写文档而不是写代码。

本指南将帮助技术文档作者开启开源项目贡献之旅，并概述在开始贡献时，你可能会遇到的常见误区。

另外，本指南会重点介绍一些参与开源贡献的好处，也会提供一些便于技术文档作者开始参与开源贡献的资源。

你能学到什么？

本文内容包括：技术文档作者参与开源贡献的方式、好处、一些潜在的坏处，以及一些新手入门资源。

什么是开源？

开源是一种软件开发与发布的协作方式。世界各地的人们通过为软件添加功能、修复bug（错误）、回答问题、翻译文本或写作教程来做开源贡献。

为什么要贡献？

为开源软件做贡献是技术文档作者和其他知识工作者回馈社会并为社会带来改变的最佳方式之一。

你可以帮忙改进你每天都在使用的软件，或者你可以从开源界前辈那儿学到东西。此外，参与贡献也是一种结识志趣相投的朋友的好途径。当你所做的贡献被人赞赏时，你会觉得自己是社区的一部分。

你可能会想自己应该什么时候参与贡献呢？嗯，如果你是开源新手，按你自己的节奏参与贡献就好啦——不要担心过早地尝试做太多。你会找到自己觉得舒适的节奏。

为开源做贡献不仅可以增加你的技能，还可以发展你的社区人脉，甚至创造自由工作的机会。

要成为一名活跃的贡献者需要花一些时间积累必要的知识和技能（尤其是因为通常文档写作所需要的技能是不同于编程的），但是，这些时间是值得投入的。

参与贡献会面临的挑战

技术文档作者在开始参与开源项目贡献时，会面临一些挑战。最常见的一项挑战就是不确定如何最大化做出贡献，特别是如果你还对项目一无所知。

你可能也不清楚你的任务应该做到什么程度或者这个任务对贡献者有什么期望。对于这个问题，有几个解决办法：你可以阅读 README 文件和/或文档，看看里面有没有贡献指南。你也可以与项目团队成员联系，并寻求帮助。

如何参与开源项目？

首先，在GitHub上找到你想要参与贡献的一个项目。你可以阅读这份教程 查看如何在GitHub上进行搜索并找到项目。

然后，打开README文件，确保你理解里面提到的说明。

接着，点击屏幕右上角的Fork按钮，将这个repo（仓库）fork（复制）下来。

使用下列命令将fork（复制）的仓库复制到你的本地电脑：

git clone <链接到仓库>

当你点击代码下拉菜单时，会看到仓库链接。

复制好后，打开包含你的新fork的目录，开始添加你的贡献。

完成后，使用下列说明将你的修改推送到GitHub：

git status //显示哪些修改已经分阶段完成
git add . // 在复制的仓库里添加更改
git commit -m "changes" //对复制的仓库进行一次提交
git branch -M changes //创建一个新的分支
git push -u origin changes //推送修改

将修改推送到复制的仓库后，GitHub页面会弹出提示创建一个Pull Request（PR，拉取请求）。创建PR，等待项目维护者将你复制的仓库合并到主仓库。

如果你不久前fork了该项目，请确保将上游的修改纳入你的本地仓库 。

如果你遇到一个大文件，并且还没有安装git-lfs的话，就用这条命令brew install git-lfs去安装一个git-lsf。

Git LFS（Large File Storage大文件存储）是由Atlassian、GitHub以及其他开源贡献者开发的Git扩展。它通过缓慢下载大文件的相关版本（译注：将音频、视频、数据集、图形等大文件存放在远程服务器上）来减少文件在仓库中的影响。

你也可以根据这个文档 安装git-lfs。

开源贡献的最佳实践

1. 确定一个你可以提供帮助的领域，然后在GitHub上找到相关的项目。
2. 阅读任何可能与你感兴趣的项目或程序相似的文档。这样你就会更了解贡献会涉及什么以及其他人做了什么贡献。
3. 搜索标注了good first issue（适合第一次做开源贡献的人的任务）的问题，并通读这些问题——这些问题通常是很容易解决的。
4. 遵循项目的贡献指南，准备好你的代码。
5. 写一个详细的PR，给出你的解决方案，并解释为什么你的方案可以解决当前问题。如果有必要，附上相关资源的链接。
6. 提交你的PR以待审阅。项目团队会讨论是否将你的PR合入仓库，并将结果更新给你。
7. 如果他们决定不接受你的PR，你就询问如何能解决他们的顾虑，这样他们之后就会重新考虑接受PR。
8. 如果他们确实接受了你的PR请求，记得表示感谢！
9. 继续寻找要解决的新问题，并在此过程中分享你的进步！

我能做什么类型的贡献？

你可以通过多种方式为项目做贡献，包括为bug修复或功能新增提PR、编写软件使用文档、改进已有文档、翻译文档和修改拼写错误。

在深入参与贡献某个项目之前，你应该首先挑选一个你感兴趣的项目，并通读该项目的文档。

参与开源项目的文档写作，有助于将自己打造成行业专家并为将来获得自由职业机会做准备。

在为开源项目写文档时，技术文档作者始终应牢记的一点是，文档读者主要是开发人员。这意味着相较于其他类型的文档，读者需要在技术文档中看到更多的技术细节。

去哪里找开源项目？

有很多地方都能找到开源项目。GitHub是最受欢迎的地方，但在BitBucket、Gitlab和其它网站也有开源项目的仓库。

如果你有一个想法，但还没有对应的开源项目，可以先把你的想法和计划放在一个README文件中。如果你不确定如何开始为一个已有的项目做贡献，那么可以查看该项目的文档或通读一些PR，然后提交自己的PR。

示例项目

• HTML5 Boilerplate项目 是一个受Web网页开发者欢迎的开源项目。项目支持通过HTML、CSS和Javascript代码来创建网站或网页应用。
• Bootstrap框架 也是一个开源项目，是一个帮助开发者快速创建响应式网站的工具集合。
• Jekyll 是一个用Ruby编写的静态网站生成器，为个人博客而设计。
• React.js文档 上有官方的React.js使用文档。
• GitHub pages 包含所有你需要知道的GitHub信息。
• Galaxy项目（培训资料） 是Galaxy项目的一个培训资料集。该项目是一个基于网页的开放平台，用于数据密集型的计算研究，其范围超出了生物科学。
• CNCF（云原生计算基金会） CNCF是开源的云原生计算，托管Kubernetes和Prometheus等项目，使云原生无处不在且可持续。

你还可以看看谷歌文档之季，它帮助开源项目优化文档，同时让技术熟练的技术文档作者获得开源方面的经验。

不同的贡献方式有很多，你总能找到适合自己的。

总结

对技术文档作者和内容创作者来说，参与开源贡献是一种很好的与世界分享知识的方式。

参与开源贡献的方式有很多，总之，人人皆可贡献。

如果你是一名软件开发人员，你便能理解在编码时为了解决特定问题，开发人员会有多频繁地进行谷歌搜索。

每个开发人员都会查看在线教程来解决他们遇到的问题。为了帮助解决你的问题，这些教程应该带有一些对于你和其他读者来说更有价值的东西。

写好一份技术教程，你需要牢记几点。

了解你的读者

清楚为谁而写很重要。你需要决定文章包含哪些内容，省略哪些内容。

你也不希望读者在阅读中途就放弃了。有时，你只需要写必要信息，不用什么都写。

参考这篇文章《如何更改HTML中的背景色》，读者想要知道更改HTML中背景色的方法。

作者直接列出了不同的设置方法，而并没有从“什么是HTML和CSS”写起。

还要记住，教程是写给入门人员看的还是资深人员看的——要尽量写明（可以在必要条件部分写明，或者只提一句教程是写给谁看的）。这将有助于确定你如何阐述内容以及预设读者的背景知识等。

写一个大纲

在开始写教程之前，先列出内容大纲。

以我正在写的这篇文章为例，为了说明如何写好一份技术教程，一开始，我把我会采用的不同步骤都写下来。

这个过程可以帮助你搭建一个合理的文章结构。你就能够解释具体的步骤，而不是想到什么写什么。

看看我写这篇文章时列的大纲：

一旦知道自己将要写什么，你就更容易专注于写作，并且不遗漏任何要点。

指出你要解决的问题

在一篇教程中，读者会首先查看该教程将解决或回答的问题是什么。这有助于读者判断所看文章是否就是自己需要的。

为了确保你的读者会进一步阅读，告诉他们你在解决什么问题，描述教程的目的，教程提供的价值，以及读者能收获什么。

你可以直接在介绍部分告诉读者该教程在做什么或者讨论什么。

回顾本文的介绍部分：当我说“写好一份技术教程，你需要牢记几点”时，我就是在告诉你，我们将讨论什么以及你将学到什么。

列出读者完成教程所需的前提条件

你应该告诉读者你将在教程中使用哪些工具、服务和资源。

你不会希望你的读者半途而废。如果他们在教程中途才得知你会用到其它工具或者他们不熟悉的东西，他们会泄气的。

只需要列一个清单，里面描述你要使用到的东西，以及这些东西是免费还是付费的。这有助于读者在实践教程之前就做好准备。

使用标题和短段

使用标题将文章的不同部分按主题分开。这样，读者每次看到一个新的标题，他们就会更清楚文章接下来是讲的什么内容。

如果你要描述一系列事情，可以试着使用标题或副标题来展示该系列中的每个元素，然后使用短段来做简要说明。

使用标题也会有助于SEO（搜索引擎优化），而且教程会看起来更有说服力，更容易实践。

提供代码片段

在技术教程中提供代码片段通常很有用。

这样，你的读者就会知道你在做什么，以及你想通过那段代码实现什么。

此外，将代码分解成小块，这也会便于你对代码进行解释（不必一次性解释所有代码）。

使用注释，描述你在某处使用特定代码的原因。另外，恰当地格式化代码也可以增强代码可读性。

举个例子：

# 以下注释描述了该程序的功能。
# 该程序输出Hello, world!

print('Hello, world!')

像这样使用代码片段。

结尾

我希望本文内容能帮助你写出清晰实用的技术教程。按照这些步骤写作，你将能够为读者提供更多的价值。

谢谢你阅读本文！

在我创建和设计产品，如APP应用程序、网站和图形制作工具时，通常会遇到两类人：一类是偏好定性叙述的人，另一类是偏好数据和分析的人。

第一类人习惯基于用户主观反馈和观点去构建产品开发框架。第二类人对第一类人的方法持谨慎态度。第二类人希望应用“Excel模型”根据数字来倒推工作。

为便于区分，我们就称第一类人为“storyteller”（讲故事的人），第二类人为“quant”（量化员）。

这两类人都想要设立有意义的产品愿景，了解用户，然后创建出大规模的工具。两者的用意都很好，只是在如何利用洞察做决策方面，采用了不同方法。

另外，他们收集、分析和部署这些洞察的方式也不同。

暂停片刻，问问自己你更像哪类人呢？storyteller还是quant？或许会对你有用。

无论你的答案是什么，我相信有一种将两者统一结合起来的方法，帮助他们在追求创建更优质更构思周密产品的路途中找到共通点。

那就是通过写作。

为什么写作对产品设计至关重要

写作被定义为一种记录连贯词汇并构成文本的书面活动或技能。学习写作要从基础原则开始：你必须学习字母表，学习如何将字母组成单词。

然后，这些单词又被放在一起组成句子。

句子组合在一起又能开始表达更深的含义。

写作是一种成因机制。它让我们深入思考自己想要表达的内容和动机。

写作帮助我们专注于最重要的东西。

而且，如果做得好的话，写作可以减少困惑。

有多少次你在看产品演示文稿时，是因为演讲者的质量（无论好坏）而相信产品优点的？例如，一个有吸引力的观点可以掩盖对用户来说真正重要的东西，并影响用户的判断。

亚马逊创始人杰夫·贝佐斯（Jeff Bezos）曾经写道：

“Powerpoint式的演讲文稿在某种程度上允许掩饰观点，抹平任何相对重要性的感觉，忽略观点之间的关联性。”

写作促使我们明白真正重要的东西：一个论点的力度和条理性，以及论点如何被论据支持或证实。

产品开发本质上是杂乱的。因为很多时候，产品即使看起来很简单，本质上却很复杂。

软硬件都是如此。我们认为理所当然的日常物品中就存在着巨大的复杂性。

汉莎航空声称，波音制造747-8需要600万个零件。

一辆简单的汽车整车可能有30,000个零件。

据估计，Android操作系统的代码量有1200-1500万行。

大型强子对撞机使用了5000万条线。

不包括后端代码， Facebook（前端和各种登录页面）的代码量就有7000万行。

结构清晰的叙述性文本（与项目符号或纯文本相比）能够帮助作者或产品设计师阐释论点背后的“原因”。

积极有力的写作促使人们进行更多的反思，更好地理解什么是最重要的，以及事物（零件、人员、计划、预算、产品）之间的关系。

最后，写作有助于创造一个公平的竞争环境。

很多时候，观点（以及因解释的方式或主体不同）会造成偏见。想象一下，当你收到一份宣传产品功能或上市计划的备忘录，你对作者一无所知，不知道作者的背景、角色或团队。

你所能做的就是评估作者文字的质量、持续性和清晰度。这样可能会带来更好的商业结果和产品设计决策。

如何提高写作水平

写作是一种通过练习可以提高的技能。我记得五年级的时候，我母亲坐在我旁边，用红墨水笔批改我为完成家庭作业写的一篇作文。

编辑文字并不容易。当时写作不好玩，二十多年后，它也不总是有趣。但是，通过打磨，我们可以拥抱写作，并写得越来越好。

“熟能生巧”这句老话当然不适用于我。尽管这样，通过强迫自己经常写作，我还是能够有所提高。

如果你正在创建产品并想要通过书面文字分享你的愿景，赢得内部利益相关者，助力更有效地沟通，那么从今天开始，你可以从这几件事开始着手。

创建一个大纲

首先，你可以拿出一张纸或打开一个在线文档，对于你想要表达的内容，开始创建一个大纲。以“为什么”为出发点来创建大纲。

你可以通过大纲来打磨你的想法，勾勒你的产品愿景。

尝试不同的写作类型

第二，你可以尝试不同有趣的写作方式来表达你的产品。

例如，你可以撰写一篇新闻稿。如果你是《纽约时报》的一名技术版块撰稿记者，会如何评价你的产品？

编写一篇具有未来感的新闻简报很有趣，让创造性思维活跃起来，并且思考他人会如何看待自己创建的产品也是一种令人愉悦的方式。

快速记下一些常见问题

第三，你可以通过起草和完成“常见问题”（FAQ）来提高你的产品写作技能。人们对你的产品有什么不理解，为什么不理解？试着思考和回复用户的这些问题。

写FAQ有两方面的好处，一是可以提高你的写作水平，二是你能更深入理解产品的哪些方面可能对用户来说是难以理解的。有了这种洞察，你可以预先解决这些问题。

将写作和产品设计结合起来

在这篇文章开头，我描述了“storytellers” 和 “quants”。在根据信息（数据、数字、反馈、证书等）作出结论和进行推断方面，这两类人代表着两种不同的处理方式。

写作可以将“storytellers”和“quants”结合起来，并为思想表达提供一个公平的竞争环境。

写作有助于我们避免过早优化。

今天写作可能对你来说是一个挑战，但它值得练习。如果你需要指点才能开始，那就试试概述零工经济的未来或者移动应用程序的未来趋势。

如果你还没有写你的产品未来状态，你应该开始了。它将有助于磨砺你的思维，让你产出更好的结果。

最终，产品未来状态应该成为每个产品创建者的北极星指标。

我在一个由200多名开发人员组成的Whatsapp群中发布了一个小广播，说多发表一些技术文章的必要性。群里的回复给了我写这篇短文的灵感。我发现很多开发人员不重视写作，我觉得这是不对的。

就像我知道很多开发人员不会写技术文章一样，我决定在广播最后补充如下文字。令我惊讶的是，有几个开发人员给我发消息说对于如何开始写文章，他们还需要帮助。所以我决定写这篇快速上手文章。

如果你想要让更多Medium用户看到你的技术类文章，可直接与我联系。提供一下你的Medium用户名并附上一篇或多篇文章链接。

如果你想开始写技术博文，却不知如何入手，也可以直接与我联系。

首先，要写出优质的内容需要付出很多努力。我知道这也是让许多开发人员放弃写作的原因。不过，在这篇文章的第一部分，我会先来说说写技术博文的好处。

创建自己的作品集

写技术博文的一个关键好处是它可以帮助你构建开发人员作品集。并且，它让你有充分的机会向他人展示你的工作技能。

另一点我认为对像Prosper Otemuyiwa这类开发人员有益的事就是无论所写教程长短，保证自己所做的事有意义。

帮助新人

你曾从他人的视频和文章受益才达到现在这个状态。这个理由足够促使你也写一些内容来帮助更多的人。

懂得更多

针对某一特定主题，你写得越多，或者说你教得越多，你就会越精通。你写的技术内容可能是关于如何搭建一个应用程序。因为你自己在构建过程中费了点劲，你希望所写文章可以帮助其他开发人员少走弯路。或者你写的技术内容是你刚学会的一个新东西，你想让全世界都知道你学会了什么。

做好上述事项，有助于你对自己的知识体系建立信心。

赚钱

是啊！钱非常重要，你坐着不动或者不做点对他人有帮助的事情，是不可能获得金钱的。你可以通过写技术内容获得报酬。只是在获得报酬之前，你必须先写出一些有趣的内容作为样本。

我知道有一些公司会为技术写作付费。一家是Scotch Development。并不是因为他们有更多的资金可以浪费，而是因为他们相信如果有正确的内容指导，开发工作会容易得多。

增加浏览量

文章有浏览量也是令我兴奋的一件事。我曾写过关于 React、Babel、webpack 和 Webpack 3.0 的文章，然后Codementor在Twitter上提醒我，浏览量达2000了。我开始为自己感到骄傲。

我认为有人阅读和学习你的内容，对你来说应该是个好事。

获得有限的机会

愿意投入时间来写技术文章的人很少。当有很多人申请某个东西时，有写作优势的人更有机会申请成功。

Auth0开放了他们的Web应用程序便于用户申请为Auth0大使。申请的条目之一是用户可以附上所写文章链接。这你应该有印象吧。

我应该如何开始写作

每次我谈到写技术文章时，都会有人问我这个问题。在这篇文章中，我将根据我的经验和我读过的其它同类文章，来讲讲如何开始写作。

1. 相信你可以

你不必以世界顶级开发人员的水平来要求自己写作。你可以就你当前正在学习的内容来写文章。

但首先是要相信自己可以写作。

2. 千里之行始于足下

许多开发人员对此感到困惑，因为他们会想“他们可以写些什么让人印象深刻的内容呢？”但是我总是说“从小处着手”。

我在媒体上发布的第一篇博文是PHP: BEYOND BUILDING WEBSITES。它不算是一篇真正的“技术”类文章。我写这篇文章只是为了输出一些东西，读者对文章的推荐又鼓励了我。随后我受邀成为一家媒体刊物上的一名作者。

这是我迈出的一小步。现在我在Scotch Development、Codementor、Medium、@dev.to等平台上发布了更多的教程。

你也试试吧。

3. 学习新技术

寻找写作素材的最佳方法是学习新技术。可以学习没人要求你学习的新框架，然后着手写作。

最近，我看到一个新的JavaScript框架，却没看到关于这个框架的任何教程。在我翻阅这个框架的文档时，发现这个框架轻量又好用。

所以，我做了相关教程。一些活跃的JavaScript Twitter用户看到我的文章后不断转发，文章就获得了更多的浏览量。

4. 主题就在你身边

有些开发人员认为主题是主要问题。其实不是的。内容质量才是最重要的。你只需要保持敏锐。

我知道Scotch Development网站有一个版块，你可以去那里找找灵感，看看可以写些什么教程。点击此处查看。

基本上，主题没有什么新的。大多数时候，都是内容上有些差异。

5. 知道你的利基（定位）

要在技术文章写作方面取得成功，你必须找准自己的定位。如果你知道自己在构建Web应用程序方面很厉害，就坚持写这方面的文章。同样，如果是在移动开发、人工智能、机器学习等方面很厉害，就坚持写这些方面的文章。

因为如果你在编写教程时犯了不该犯的错，读者会把你当成迷糊粗心的人。

6. 独特的写作方式

在写作时，你必须尽可能写得简单且让人读着轻松。就像是在向另一个开发人员解释一样写作，你要用简单的术语就能让他们理解。

你可以插入一些有趣的GIF图片、短视频、屏幕截图等等，吸引读者注意力。

7. 获取反馈

兄弟姐妹们，不要以为自己什么都懂！那样只会是搬起石头砸自己的脚。征求意见，对于批评意见持开放态度，因为批评在所难免。

读者有一些不清楚的事情时，保证他们能够通过邮件或Twitter与你探讨。

8. 别停止写作

我本不该加最后这一点，但是还是想说，一旦开始，即使受到一些无端批评，也不要停止写作。

认真修改每一篇文章，勤加写作，终会有收获。

总结

我相信你一定从我这篇简短但真挚的文章中有所收获。欢迎你在Twitter@goodnesskayode上与我分享你的想法。

如果你能在Scotch.io、Codementor、LinkedIn和Dev.to阅读我的文章，我也会非常高兴。

我在开源社区工作了将近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的编辑人员，帮助审阅这篇文章。

谷歌有一门技术写作课程，我最近刚学完这个课程并且非常喜欢。课程大约需要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%。

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

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

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

近年，有调查表明良好的文档对开发者如何选择和使用开源非常重要。

2019年首届Google Season of Docs（GSoD，即谷歌文档之季）项目，共收到了近450份技术写作者的申请，最终有50多名技术写作者被录取。

作为入选参加GSoD项目的技术写作者之一，我想分享一些关于如何为GSoD项目做准备并制作有竞争力申请书的想法。

目录

• Google Season of Docs是什么？
• 哪些人有资格参与该项目？
• 参与该项目的好处
• 让你的GSoD申请脱颖而出的5个建议
• 我的GSoD项目经验
• 有用的参考资源

Google Season of Docs是什么？

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

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

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

哪些人有资格参与该项目？

根据谷歌的规则，在注册时你必须已年满18岁。你还必须有技术写作者的实践经验，并且有资格在你的居住国工作。

如果你符合这些资格，就可以申请参加GSoD项目。

参与该项目的好处

参加文档之季项目，有很多好处，比如：

你可以获得一笔津贴

在完成GSoD项目后，你会获得由谷歌支付的一笔津贴。值得注意的是，这项津贴是可选的，因此你必须在申请阶段表明你希望获得津贴。

津贴金额是基于申请人所在地区的情况来计算的。有关津贴的完整详细信息，请参考此处。

你可以提高自己的技能

参与GSoD项目的另一个明显好处是，可以提高你的技术写作技能。

你可以扩大自己的人际圈子

除了提高自己在技术写作方面的技能，你还有机会与在开源领域做着了不起事情的人一起工作。

就我而言，我有机会与VideoLAN组织合作，这意味着我必须与该组织的社长和项目的主要贡献者密切合作。

你可以获得推荐和介绍

在申请任何工作时，一封好的推荐信往往有助于提高你申请的成功率。

与文档之季项目的导师紧密合作，将有机会获得丰富的推荐和介绍资源。

你可以获得未来进入谷歌的机会

如果你准备申请谷歌的技术写作职位，那么与其他申请人相比，你简历中的文档之季项目经验会让你有更多优势。

你可以成为一个开源贡献者

除了上述所有好处之外，参加文档之季项目意味着您可以为开源项目做出贡献。这有助于人们打破开源贡献仅适用于软件开发人员的刻板印象。

让你的GSoD申请脱颖而出的5个建议

以下5个建议，帮助你为GSoD项目做准备和制作有竞争力申请书。

在你的博客上创建和发表文章

在GSoD项目中被录取为技术写作者的最重要标准之一是能够证明你以前有写作经验。

谷歌和你想从事项目的拟派导师需要确信你是从事该项目工作的合适人选。这意味着他们希望能看到你创作的大量优质文档和文章。

值得一提的是，现在去创建一个博客或在现有博客上发布更多内容还不算太晚。

如果您已经有一个博客，那么在你提交申请之前、期间及之后发表更多优质文章是个不错的方法。如果你没有任何博客，那么使用Hashnode's Devblog或你喜欢的平台创建一个博客并发布优质文章仍为时不晚。

选择合适的开源项目

事实上，我再怎么强调选择合适的开源项目的重要性也不为过。这是因为它对你是否能进入该项目有重大影响。

以下是我对选择合适项目的想法：

• 认真查看所有已录取的项目，并尝试选出至少5个你感兴趣的项目。
• 选出至少5个项目后，再次浏览，将项目数量缩减至2到3个。
• 虽然可能在申请阶段只专注于一个项目是合理的，但我鼓励你至少申请两个项目，这样你至少被一个项目录取的机会就会更大。
• 对于你选择的每个项目，加入其所在组织的沟通渠道，并让项目的维护者知道你对该项目的兴趣。这样，你将能够与导师建立关系。另外，请注意，导师选择人时并不仅仅因为申请人拥有必要的技能，还因为他们认为申请人能够与他们合作。因此，当你向导师发送信息时，要明确说明你的需求。最重要的是不要因为他们没有立即回复而感到沮丧，因为大多数导师都是有其他全职工作的志愿者。
• 不要被动等待。对项目进行大量研究，去发现并理解你需要了解的所有内容，如果你有任何疑问，请向该项目的拟派导师寻求帮助，或询问该社区的其他成员。
• 最重要的是，在研究过程中，写下任何有用的信息。一些信息在将来若你被某项目录取后，可能会用上。而一些信息可以用于优化你的提案。

撰写一份提案

很多人不知道这一点，但写一份提案是至关重要的。它让你清楚地了解项目的目标、你完成项目所需的时间线、你需要了解的内容等等。

除此之外，写提案还可以向你的导师展示你对该项目的目标、为什么你认为你是这个角色的合适人选、你的经验、项目时间线等等。

写完提案后，将其发送给项目的导师进行审核。他们的审核将帮助你从导师的角度了解项目的要求。我在Resources部分添加了我的GSoD提案的链接。

至少为开源组织做出一项贡献

文档之季项目并不像Google Summer of Code（GSoC，即谷歌编程之夏）项目那样要求你对感兴趣的开源项目至少做出一项贡献。但是做出贡献绝对可以提高你被录取的机会，所以试试吧。

在申请截止日期后仍在社区中保持活跃

提交申请后，尽量在该开源组织中保持活跃。这可以最大程度地向导师们表明，你对这个项目和开源社区充满热情。

我的GSoD项目经验

在去年的GSoD项目中，我有机会与VideoLAN组织合作开展VLC用户文档现代化（重写）项目。

在我的提案被VideoLAN组织接受后，我的导师和我就商定了我在GSoD项目中要实现的目标。

这些就是我的目标：

1. 重构文档。
2. 更新文档以适应VLC的现代版本。
3. 使用Sphinx和ReadtheDocs将用户文档迁移到Gitlab。
4. 删除过时的图像和信息。
5. 重写用户文档，使其易于理解。
6. 使用国际化版Sphinx进行翻译。

我对VideoLAN组织和VLC有了更多的了解，我发现了很多我从未了解的VLC功能，并且我学会了如何使用Sphinx文档平台并重构文本。

我的技术写作技巧也得到了极大的提高。总的来说，参加GSoD项目是2019年我经历的最好的事情之一。

有用的参考资源

以下是一份有用的资源列表，帮助你了解更多关于文档之季项目和技术写作的信息。

• My Accepted Season of Docs proposal
• Google Season of Docs Project Report
• Open Source Contributions: A catalyst for Growth
• Technical Writer's Guide
• Season of Docs Slack channel
• Awesome Technical Writing

喜欢这篇文章？Twitter上关注我@Didicodes。