播客 Ep. 22 对话资深文档工程师 Allen Xue：16 年技术文档写作之路

Miya Liu — Thu, 14 Dec 2023 13:00:00 +0000

今天我们的嘉宾是技术文档领域的资深从业者 Allen。

Allen Xue

2007 年，他在英语专业毕业后，进入知名的世界 500 强公司。在技术文档还是一个非常新的领域的时候，他接受了专业的技术文档写作培训，接触了先进的系统和工具。

后来，他进入创业公司，继续从事资料开发、社区运营和生态治理工作，并且带领团队创建技术文档中心。在节目中，他聊到自己丰富的经历，带我们了解技术文档写作领域的全貌，也分享了关于学习、求职、实践等等经验。

希望你喜欢这期节目，欢迎你关注我们的播客，并把节目分享给更多朋友。也欢迎你发邮件分享自己的故事，也许我们会邀请你作为 freeCodeCamp 播客的嘉宾。你可以在这篇文章中找到邮箱地址。

欢迎在 https://chinese.freecodecamp.org/ 查看更多免费的编程学习资源。

主要话题

01:36 喜欢看杂书的英语专业生
08:00 最初接触技术文档是给游戏写资料
12:48 到诺基亚芬兰总部接受技术文档培训
17:56 将技术文档作为职业发展理想
20:03 从上海回到成都，进入西门子
21:47 在 freeCodeCamp 学习前端开发
23:36 到美国参加敏捷开发和技术文档写作培训
26:23 Doc as Code
28:06 大型外企和创业公司中技术文档工程师的工作日常
33:58 技术文档写作相关的系统和工具
39:37 DITA 达尔文信息类型体系化结构
43:20 什么是好的文档，什么是差的文档
50:11 如何让文档被用户发现
53:00 值得骄傲的技术文档
55:03 有帮助的人和学习资料
57:33 在思科写市场文档，促成产品销售
1:06:58 RISC-V 简介
1:09:26 RVspace 生态社区
1:15:14 在创业公司中搭建技术文档体系
1:21:46 计划/写作/评审/发布/归档全流程
1:23:30 国内技术文档从业现状
1:25:33 技术文档从业者的薪资
1:27:02 最重要的是写作而不是技术
1:31:40 英语是一个非常好的工具

提到的资源

谷歌文档之季（Google Season of Docs）项目申请指南

Narcissus91 — Tue, 19 Jul 2022 07:00:00 +0000

原文：How to Crack the Google Season of Docs Application Process for 2020，作者：Edidiong Asikpo

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

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

作为入选参加GSoD项目的技术写作者之一，我想分享一些关于如何为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项目中要实现的目标。

这些就是我的目标：

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

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

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

有用的参考资源

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

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

文档 - freeCodeCamp.org