JSConf China 2019 文档写作 讲稿中文版

JSConf China 2019 文档写作 讲稿中文版

准备讲稿的时候,一直有意同时提供一份中文版。但是鉴于整篇讲稿重写了很多遍,一直没有办法完成。现在讲完了,补上中文稿,算是给这次JSConf之行收个尾。这篇文稿不完全是逐句翻译,大体是同样的意思自己在用中文讲一遍,顺便把一些遗漏的补上,希望可以让更多的人受用。

英文讲稿+幻灯片在这里:The Treasure in Writing Docs – A True Gem in My Learning Folio as a Work in Progress Web Developer · Wei's home in the open web.


大家好!

预留一屏聊聊第一天的事情

大家参会的第一天感觉如何?来聊聊我的学到的东西吧。

上午先是学到TypeScript可以帮助我们大规模可维护的JavaScript,效益是大家都有体会,不过不怎么容易量化。

PWA不仅是Chrome浏览器里的小恐龙,其实有一大套工具帮助我们可以丈量页面各种指标,做更好的适合资源受限时的UI。

下午大多数时候我都在紧张我今天的演讲,林林总总又改了一边。不过我圆桌会议的时候回来了。个人觉得圆桌会议环节真的很有趣,TypeScript和GraphQL备受热议,就是感觉什么问题放在韩骏老师的团队面前都不成问题,这让我们脑子不那么聪明的有点怄火😠(开个玩笑韩老师。另外还学到阿里巴巴的小秘密,他们有个中心化的服务专门用来区分所有的地址对应的环境。所以我很期待今天晚上的圆桌会议,尤其是今天的议题看起来都很有趣,圆桌会议可以问我自己感兴趣的话题,所以很期待。

那么,这些是我昨天的总结,大家都学到了什么?假如一会我们聊起天来的话我可能会感兴趣大家的收货哦。

写文档都学到什么

我们进入正题吧。今天,我会讲一讲关于文档的事情。特别是,撰写文档可以不仅是我们给开源项目做贡献的机会,更是一个深入学习的难得机会。开始之前,想顺便了解下,在座的各位有多少人自认为“新手开发员”?

(只有零星几个人举手,这让我有点吃惊😅

其实我很珍惜作为新手的感觉,无奈没有办法永远霸着新手光环。不过我自认永远"work in progress"(双关语,没完成的pull request也都标WiP),“工作进行中”,享受把事情越做越好的感觉。

我在东南亚的一家电商工作,我们团队是用React的。不过今天我带来的内容主要是来自于我过去一年给React Redux写文档的经历。从去年秋冬季开始我在帮React Redux的维护者Mark Erikson撰写文档,这个新的文档站里有相当一部分文档是我写的。


这个机会又让我后续参与了Docusaurus这个项目的维护,后面又有给Docusaurus写文档。给不太了解Docusaurus的小伙伴们介绍一下,Docusaurus是一个基于React的文档静态站生成器。


现在大家可能可以看出来,我对文档特别有感情。这是为什么呢?卖个关子先啊,这是我今天想要分享的内容。

做前端的四年

原文地址aworkinprogress.dev

我们今天还会聊到学习。既然如此,那也请允许我和大家分享一下我个人职业发展的一个位置。

我作前端开发,最近刚刚满4年,前两天刚刚发了一篇文章回顾这四年,原文链接在这里。不过,我觉得我并没有什么做开发工程师的天分,也不是计算机科班出身。不过可能也因此我更适合和大家分享关于学习的事情,因为我深有体会是哪些事情让自己有所进步的。

第一年,觉得前端很好玩

第一年不怎么成熟,其实我是因为觉得前端就像是玩乐高才开始做这一行的,做需求就是从需求文档、接口文档、设计图拼网页。觉得很好玩,“玩”了很多项目。

第二年,“加入这个专业”,觉得周围人都很厉害

我在第二年加入了我现在的团队,当时所有其他同学都是计算机系毕业,都特别厉害,厉害到我看他们代码,觉得都特别好,就是不知道怎么能写得出来。就有点进入这个专业,碰见了专业同学,但是小有压力,这个感觉。

第三年,做很多需求

第三年基本上就在埋头做需求,做了很多需求,不过也净做需求了,觉得有点迷失。所以我决定去参加个大会找找灵感,可能今天也有人是抱着这个心态来的,那我很希望能够把这个精神传下去。我去了在美国盐湖城的React Rally,也是在那个会上遇到一些特别友善又贡献卓著的开发者,包括Redux的维护者Mark,也是借此了解到文档的项目,并且后续参与撰写的(不过你不需要去参会才能参与)。

第四年,组织团队内部分享

然后第四年,我花了很多时间组织团队内部的分享。我自己也在这个讲台上分享过很多东西。这是一个我自己特别自豪的事情,估计能搞出另外一个单独的演讲。啊,不要扯远。我觉得演讲和写作有很多相通的地方,也一直相信一篇好的演讲稿也是一篇好的文章。他们也都能够帮助到我们个人学习和发展,不过今天,我们就只讲写作。

今天的提纲

  • 写文档学到什么
  • 技术写作的挑战
  • 文档贡献的价值

作为前情提要,今天我想要先分享下我们参与撰写文档能够学到什么东西。然后我想聊聊于我个人而言文档协作最大的挑战,和我自己为了应对这个挑战经常甚至每天练习的事情。最后,我会再多提一些文档贡献的动机,这可是一个独一无二的提升我们个人价值的机会。

写文档学到什么

……回到2018年的React Rally

让我们回到2018年的React Rally。这是我第一次参加大会。我特别内向所以就没怎么认识新朋友(还认错一位讲师,尴尬)。不过会议后面一天,我刚好出现在了一群开发者和讲师在闲聊的餐桌边上。这时候Mark也在,然后某个契机他就提到他近期在推进重写Redux和React Redux的文档,问我们愿不愿意参与。

你会怎样回应呢?是欣然接受还是委婉拒绝?

我那时候有点想参与,但是我有点不确定自己到底能做什么。Redux和React Redux都是超多关注的项目诶,觉得自己资历不够啊,对于项目的理解也不太有把握,而且写作挺难的,要用英文解释技术问题就更难,没动笔就觉得自己会词穷。

所以那之后我就一直在想自己到底能做到什么程度。现在我觉得,要是你天天想着一个事情动心想去试试,那你不如就去试试。

所以两周以后我回到家里就又去联系了Mark,然后Mark其实已经做了很多准备工作了,有两个GitHub issue,他在里面列了整个文档的纲要,很多参考资料,甚至有些篇目还有更具体的大纲。

也就是这个时候我意识到,我不怎么懂React Redux诶。

假如你不怎么熟悉React Redux的话,我们来看下,用React Redux我们写的代码,去掉很多细节,大概是这个样子的:

import { Provider } from 'react-redux'

ReactDOM.render(
	<Provider store={store}>
		<App />
	</Provider>,
	rootElement
)

一般我们会先创建一个 store ,这个会包含应用的所有数据,然后我们要把这个 store “提供”给我们的React app。接下来,我们就可以像已经有这些数据一样地去写我们的组件:

const Greetings = (props) => {
	const myName = props.myNameFromTheStore;
	return <div>
		<input onChange={props.changeName} />
		<h1>Hello, {myName}!</h1>
	</div>;
};

不过,直到我们真正把组件“连接”到Redux,这些数据才会真正被传下来。这里有两个拗口的变量,一个是用来从 store 里取数据的,另一个是用来向 store 发送指令的,这两个

import { connect } from 'react-redux';

// const Greetings = ...

const mapState = (state, ownProps) => ({
	myNameFromTheStore: [state.name](<http://state.name/>),
});

const mapDispatch = {
	changeName: (newName) => ({ type: 'change_name', newName }),
}
export default connect(mapState, mapDispatch)(Greetings);

给大家看这几段代码的用意主要是想提,你看这些API非常的“陈述式”(declarative)。所以我从第一天写这几行代码从来没遇到过什么问题,从其他人那里直接照抄的。这两年从来就没想过React Redux的这个 connect 函数到底在做什么。

回过头来,这简直就是“只懂名字不懂原理”的完美诠释。大家认识理查德·费曼吗?加州理工学院的物理教授,诺贝尔奖获得者。他把物理这么高深的学科讲得深入浅出,如果没有他,我的大学物理应该不会过的吧。

因为他的课程和演讲实在是太赞了,后来就有人把这些转录成文稿出版。其中一本杂文集,叫《发现的乐趣》,有兴趣的小伙伴可以去读一读,在这里费曼讲过一个故事。他说他小时候有一次和小伙伴们玩,看见一种小鸟,小伙伴问他知不知道那是什么鸟,他说他不知道,然后小伙伴就嘲笑他说他爸爸怎么没教他呢,这个鸟叫“XXX”。其实,他爸爸早就告诉他那个鸟叫什么名字,还告诉他了好多个语言里(在他讲这个故事的视频里,还有中文,可惜我没听懂😂)这个鸟叫什么,但是,这不意味着我们懂这个鸟到底是什么,有什么特征等等。借此,老费曼让小费曼理解到,知道一个东西的名字跟知道它的原理根本不是一码事。

想起这个故事我就发觉这简直和自己只会调函数不懂它的原理简直如出一辙嘛。

这就有点吓人了。大家想一想,我们现在用的库啊、工具啊之类,他们的“开发者体验”都做得特别好,意思就是说接口都非常直观明了,把复杂的逻辑全都藏在下面。这对于使用来说当然是个好事情。不过,大家有没有发现,我们现在做前端,好像不怎么需要刨根问底了?

作为一个开发者,假如我们的日常工作都不需要我们了解原理,那我们什么时候去学习它们呢?在我们埋头做需求的时候,什么时候往另一个方向探索、更深层次地理解我们的领域呢?

举个例子,我们来问问用过React Redux的小伙伴,你们有没有想过, mapStateToProps 这个函数,什么时候运行?

  • 每当store state变化的时候,所有的mapStateToProps都会跑的喔😯
  • 就是说 mapStateToProps 需要很快

每当我们给 store 发一个action的时候,所有的连接到它的组件,因为都需要看一下自己关心的数据有没有变化,他们全部都会运行自己的 mapStateToProps 喔。这意味着什么呢?我不知道大家的页面上有多少组件。我们的页面,尤其是PC端,屏幕一大,有时候上百个也说不好。所以一不小心就是上百个组件同时跑他们的 mapStateToProps ,这就是说,这东西跑起来最好比较快。

我们 React Redux 最新的文档里,会告诉大家 mapStateToProps 的推荐实践 – 它们的效率越快越好,能memoize的话就memoize,不要犯傻往里面放异步请求,另外他们最好只返回它自己关心的数据,因为它的返回关乎那个组件会不会接下来运行他们的 render 函数。

虽说近些年我们的圈子也推崇不要过早地优化、不要解决还没有出现的问题什么的,但是大家同意不同意,这个原理我们最好能懂,就是 mapStateToProps 这个事情,它有它的特征,但这些并不是我们看方法名就能看出来的。一不小心,我们可能就成了费曼教授故事里的那个孩纸,只会调函数,不懂背后的原理。

我因为大学的时候学了数学专业,恰好懂很多没什么卵用的晦涩的知识。这一次研究这两个拗口的方法,猛然间发现其他人好像也并不怎么知道他们究竟应该怎么用,最少在我的小团队里,我好像是在这个晦涩领域懂得有点多的人了?因为我看到很多身边的代码,可以说完全没有把 mapStateToProps 的速率放在心上,这是另一个话题,但这在我心里产生了一个神奇的效果,我忽然对于React Redux这个话题多了很多兴致。

通过文档写作到底学到什么?

聊到这里我们就先缓一缓。要是我不告诉大家,这些理解到底是如何通过文档协作发生的,那这个演讲就没有起到我预期的目的了。

🤞 文档写作提供透彻了解这个领域的机会

首先,文档协作为我们透彻了解这个领域提供了一个绝佳的契机。假如我只是在解决日常代码问题,那么那个问题一旦得以解决,后续的理解到什么程度就因人而异了。像我可能搞一些有的没的占用了很多时间,要么就是赶时间,总之就是很少深究。可能这也是为什么有时候我们领域很在意“多年经验”,就是因为这些经验要慢慢积累嘛。

可是,如果我们要写文档,这就不一样了。这简直就是让我们火力全开去学这个东西的契机。Mark有一个神库,里面汇总了特别多关于Redux和React的资源链接,这个库也是大一万多的星星。在给React Redux写文档以前,我大概看过里面的一两篇文章吧😅不过为了写这个文档,我有时间就去读里面的内容,读到后面看看提纲就能知道那个作者的点是什么。这个感觉,我相信所有曾经“穷尽”过一个领域所有文字的小伙伴们都能理解。

☝️ “教学”是最好的学习方法

第二,“教学”是最好的学习方法。我们最爱的物理教授又回来了。他提倡一个被我们成为“费曼技巧”的方法,就是说学一门知识,学习的方法,是找一个小朋友看看能不能教会他,在这个过程中,找到自己理解中遗漏的部分,然后反复精炼自己的语言。

我觉得写文档就是这个过程不断重复,直到文档写好为止。

✌️ 领域专家会来过目我们的文档,并提出建议

第三,我们要是给一个受欢迎的库写文档的话,人们会来看我们的pull request。而且不是普通用户哦,项目维护者,发起人,领域专家,他们会来看。因为他们关心社区如何理解这个库,他们关心我们如何教新人,他们关心怎么写官方文档。

但对于我们来说,难道这不是最好的学习机会吗?所以,我的第一份文档进主分支那天,想到我从Mark以及前序的种种讨论中学到的东西,我就在想

这……每个人都会想做这个事情吧?

但……并不是这样。事实上,写文档的人极其稀少,都没人跟我抢。

最开始我很不理解,我还以为这种好事情大家都会争着去做。可是后来,我也大体理解了为什么这个现象并没有发生:

  • 我们并不知道我们可以去写文档

首先,我们并不了解我们可以去负责写文档 – 不过过了今天你知道了。

  • 文档贡献需要不小的时间和精力付出

然后,就来到了时间和精力付出的问题。修个错别字什么的不算数,写文档要花费的精力着实不小。而且涉及和项目维护人的合作、沟通,可能还会反复修改文稿。

  • 写作的确很难

连普利策获奖者也会告诉我们写作确实很难,它对每个人来说都很难。尤其是,我们的主业并不是写作,所以这其实是完全独立的一项技能,我们中间大多数都没有特别训练过。

  • 理解和解释技术问题的挑战

不过,我觉得最核心的挑战,还是在理解和解释技术问题上。尤其是,这个库不是我们写的,我们却要教别人如何去理解它的时候,这就需要我们先对这个库有透彻的理解。很多时候这几乎等同于我们对源码有多深刻的认识。这有时候就已经挺难的了,然后就是要通过写作解释给别人,让读者也懂。还没到用英文的问题,这要是高中语文老师看到我,肯定笑话我怎么老是词穷。

理解和解释技术问题的挑战 🧙🏻‍♀️🧙🏻‍♂️

这就来到了我们今天分享的第二个部分,想来聊聊我在过去这年陆续学到的一些可以帮助我们理解和解释技术问题的练习。这些事情我到今天也在做,可以说对我的工作习惯有不小的改变。大家今后也可以试一下。

首先,我觉得理解和解释技术问题不是两个问题,而是一个问题的两个方面,我觉得说是手心手背也不为过。要是一个问题只是在脑海中理解了,没有给任何人讲过,中间很有可能有缺漏我们没有意识到。这不是吓唬人,当代数学家安德鲁·怀尔斯当年关于费马大定理的证明,第一次公之于众的时候,就被发现中间有逻辑空缺,他后来又花了大半年才补上。所以,直到给人解释过一些问题,确保那个人理解之前,先不要那么确信我们已经理解这个概念了。

所以,基于我在写React Redux文档过程中个人的收获,在那个项目告一段落之后,这大概是去年年底吧,我决定把技术写作作为一个技能来培养,提上日程。不过我并没有想转行,作为主业,我还是想写代码。所以我就想着能不能有一些可以系统性地实施的练习,可以让我慢慢地提升这个能力。

而且,大家不要看我今天在这里演讲,侃侃而谈,讲稿也是洋洋洒洒写了那么多。其实我的讲稿是反复修改打磨过的,前前后后重写了很多遍。我本人是一个很不爱讲话和写东西的人,和我吃饭很容易冷场和尬聊。我的 A Work in Progress 技术博客里面是一大堆没有完成的、子弹头构成的零散笔记而已。提这个背景也是想和大家说,技术写作的能力是可以练出来的,而且说不定惜字如金这样的天分还可能在文档写作中更受用呢,毕竟精炼是咱们的特长嘛。

那么,我们就来聊聊可以帮助我们稳步提升写作能力的技巧吧。

让我想问大家一个问题:假如你读到一篇有趣的技术文章,看了一个不错的演讲,或者解决了一个技术问题,抑或是看到一个有趣的库,你会怎么做呢?

💡 用自己的语言提炼总结,找个人给他讲一遍 💁🏻‍♂️

咱们今后,可不可以不要只是加个收藏夹。我们可以用自己的语言总结下里面的内容,然后找个人给他讲一遍。

我自己的实践是,每当我第一次解释一个东西的时候,几乎总是比我预期的要差劲。在脑子里,所有事情好像都是很清楚的,一二三,结果从嘴里出来,就完全不是那么回事了。这个大家试几次就知道了,费曼教授提的逻辑空缺是真真切切在那里的。不过,你讲两三遍就能补上了,还能熟悉了,这个感觉可是特别赞。

🌟 一对一分享 🌟

我觉得做这个事情最好的方法就是一对一分享了,最好还能保持规律性。我知道这听起来有点奇怪,不过其实很多人建议过这个,今年5月我去立陶宛参加YGLF这个会,有幸和You Don't Know JS的作者Kyle Simpsons聊天,他也是推荐者之一,所以大家不妨试试。

如果你从来没有尝试过,可能不知道该如何开始。如果你还记得我今天演讲一开始和大家聊过我昨天学到的东西,其实大体就是那个样子,只不过我们关于项目的讨论会少一些条目、多一些深入探讨,但对话大概就是那个样子的。你可以和你的项目伙伴每天碰个头,我觉得我现在有机会每天进行这个练习实在是太幸运了,简直没有理由不把事情都理解清楚。或者如果你们团队有导师制度的话,我觉得你们规律性地交换谈一谈各自学到的东西,这是个双方受益的事情。

所以,再重复一遍,强烈推荐,一定要试几次。

如果说你没有一个稳定可以和你一起做这个事情的伙伴的话,还有一些可以实现类似效果的事情:

  • 分享你的总结
  • 如果是代码衍生出的技术问题,可以写几行注释来解释一下情况
  • 在博客上开一个“简短笔记”的区域

你可以发推(我听说国内是知乎比较活跃?)分享你的总结,但是不要只是retweet,写两句话总结下大意。

如果是代码衍生出的技术问题,不要只是把连接扔回来就结束了,可以写几行注释来解释一下情况,这样看到这段注释的人可以节省一些时间不用把那个文章再重新读一遍了。

关键之一是任务要足够小,这样每天都可以练习

我发觉,这个事情的关键是,不要太有野心,这个事情要让你能够舒舒服服加到日常作息里才能切实起作用。

那个一对一分享,就是因为它超低调、超微缩、不会被录下来,我们才会足够放松能够不介意每天都做这件事,而且这也不需要像准备一次演讲一样大动干戈,其实就是每天碰头之前花几分钟捋清一下思路,但这对我们关于项目的掌控和理解无形中提了要求。

假如你是在博客上开这个简短笔记的区域,就不妨把你的博客布局做得适宜这种小型笔记的呈现。不然你一篇长博文可能几个礼拜都写不完,最终就全都搁浅了。可是如果你从子弹头笔记出发,不断优化你的解释,可能几个礼拜以后你就有一小叠笔记,可以组合成为一篇不错的文章了。

这里图片例子是Stefan Judis的“今天我学到了什么”,我特别喜欢,把我自己的博客改成了这个布局,也借这个机会分享下。

💡💡 不要复述代码,告诉我们代码背后的意图

这是我学到第二件关于解释技术问题的技巧。

其实文档做的事情,是把机器理解的语言,变成我们理解的语言,或者说,缩小我们认知和机器语言中间的鸿沟。机器语言一般比较按部就班,我们人呢,理解意图比较直观。所以,不要直接重复代码,解释问题的时候,多注重告诉我们直观感受,如何去理解它。

比如,我不知道大家有没有遇到过这种代码注释,就是你要是把代码大声读出来,简直就和注释一字不差。这种注释看起来好像是在解释代码,其实就是复读机而已,并没有什么卵用😅还可能让你觉得现在不仅代码读不懂,注释也没读懂。

const factorial = n => {
  // create cache if there is none
  if (!factorial.cache) {
    factorial.cache = {}
  }
  // if n is in cache then return it
  if (factorial.cache[n] !== undefined) {
    return factorial.cache[n]
  }
  // if n is zero, set cache of n to 1
  // otherwise set it to n multiplied by the factorial of n - 1
  factorial.cache[n] = n === 0 ? 1 : n * factorial(n - 1)
  // always return from cached results
  return factorial.cache[n]
}

不要这么搞。。相反,像一个向导一样,

const factorial = n => {
  // initialize cache
  if (!factorial.cache) {
    factorial.cache = {}
  }
  // short circuit and return cached result it is already there
  if (factorial.cache[n] !== undefined) {
    return factorial.cache[n]
  }
  // by definition, fac(n) = n * (n-1) * (n-2) * ... * 1
  // it is possible to recursively compute factorials with 
  // existing results by fac(n) = n * fac(n-1)
  // with initial case of 0 to return 1
  // the cache further reduces computations needed
  factorial.cache[n] = n === 0 ? 1 : n * factorial(n - 1)
  // cache[n] was just computed and we're guaranteed for a return
  return factorial.cache[n]
}

我们来重新看一下这个memoized的阶乘方法。比如告诉我们一开始要初始化,告诉我们从缓存里返回是在short circuit来节省运算 – 这些是在解释代码背后的动机。

然后运算那一步可能是这一个小方法里最复杂的,记得帮我们回顾下阶乘的定义,然后根据这个定义,递归那一步并不难理解,但你可以多提供一个视角和提示。

换句话说,告诉我们代码做这件事情的原因,用自己的语言解释复杂的原理。假如你还是有点没有头绪,可以考虑这样开头:

  • 这部分程序做的是……
  • 我们的实现方法大体是……

我们自己在读代码的时候,也可以像这样试图给自己解释,写一些笔记,比如这样:

  • mapStateToProps 做的事情是……
  • mapDispatchToProps 做的事情是……
  • connectAdvanced 的初衷是……
  • 确实需要客制化优化运行效率的场景是……

这样没多久,我们就有一大把这些小笔记,基于这些东西写文档,就容易多了。

💡💡💡 写文档的时候,也可以以动机来开头

同样的技巧也适用于文档。比如,我现在写文档,几乎通通以这句话来开头:

这篇文档的目标是……

这句话一放下来,对我来说,它有两个帮助。第一,它让我非常明确这张纸就是为了解释好这一件事情,可以让你的内容紧凑围绕这个话题。第二,它开启“对话模式”,接着这句话,你很容易以对话模式来延续要解释的内容,这可以让我们的文档写得更易懂。

Then, what about English and writing?

终于到了这个最难搞的问题了。首先,我想先提一句:

在网上,可以纠正我们语法错误的人远比付出努力写文档的人要多。

所以,千万不要因为觉得英文受限就不去尝试文档贡献。况且,没有人能打保票自己的英文就是完美的。我的英文超级不完美,我讲英语会带着我在各个不同地方染上的口音。但这不是关键问题,关键是,你愿不愿意用你的语言能力去做贡献(包括,为此提升自己的语言能力)。

有了这个共同认知以后,我们可以分享几个技巧。

除了综合提升英文能力以外,这个大家肯定各自有各自的方法,比如看电影啊听音乐啊读书啊,这之外,有两个事情是我在文档写作里使用频率最高的,和大家分享一下。

第一,是特别经常使用同义词字典

同义词字典简直就是写英文的作弊模式。为什么呢?因为从一堆词里挑一个,和拍脑子空想相比,要容易多了。更何况好多字典可以让我们递归式地无限接近自己想用的那个词,还给例子,有这两个贴心的功能,可以大幅增加我们可用词汇量的范畴。

那么如何能够提升自己挑词的准确度呢?这个就要考多多阅读了。可是阅读比写作容易多了喔。

顺便一提,这个作弊方法其实英语母语的人经常用。我们中文使用者大概是因为中文的特质,好像不怎么用同义词。那么,今天你也学到了,同义词字典可以经常用起来。

第二,要特别注重语法审查

这个语法审查是我们容易忽略而且不太确定要怎么做的一项重要工作。我个人的体会是,其实语法和拼写错误非常客观,所以这个工作可以非常的机械,我们是完全可以保证它的效果的。我的技巧就是,复审自己的文稿的时候,每一次专门针对一种问题。

  • typos / 拼写
  • punctuation / 标点符号
  • subject-verb concord / 主谓一致
  • tenses / 时态
  • passive tense / 被动语态

如果你每次复审自己的文稿,就只针对这一个问题,你很难会遗漏的。

回顾一下

我们聊了很多东西了,让我们一起回顾一下。

我们先谈了如何更好地理解和解释技术问题。然后,我们分享了一些每天可以进行的练习。我们同意我们要直观些,注重技术问题背后的动机。我们也聊了一点点英文的使用经验,记得要复审自己的文稿。

大家感觉如何?

几个月以后……

说来也巧,几个月以后,我在Twitter上看到Mark在找人给Redux的Q&A加一个条目,这一次,假如是你的话,会如何作答呢?

我显然是毫不犹豫地举手啦。其实中间有其他人说要帮忙,所以我就多等了两三个礼拜,结果还是没人提PR,所以我就提了。在那两三个礼拜里,我差不多又把关于这个问题的讨论通通读了一遍,也产生了一些自己的理解。最后把这些想法整理归纳,以官方文档的前后文写出来,那个写作+提PR的过程,竟然异常顺利,然后很快就合并进主分支。我自己也惊呆了。

万一你需要多一点点的动力开始尝试文档贡献

📚 网上已经有那么多教程和博文了,再写文档算是重复工作吗?📚

你可能会想,如果说一些条目已经被大家反复讨论过了,再放进文档里,算是冗余的工作吗?其实,我觉得这些问题之所以被大家反复讨论,可能恰恰是因为它们既重要,官方文档又没有提,才会导致大家要到处问、到处答的。

🥇 文档占据我们理解框架过程中独一无二的黄金位置

官方文档简直就是大家学习这个库的黄金位置,而且大家默认会认为文档的可信度比其他素材要高。如果说大家要找的问题的答案,在官方文档里已经解答了,那么大家就不用再去其他地方找了哦。这会节省大家的时间。这其实会节省更多的时间,因为那些文章可能根本就不用被写出来。这样我们整个社群可以算是少一个问题,这就很厉害了。

👩🏻‍💻 这能和日常工作结合起来吗?👨🏻‍💻

假如你的日常工作有和这个库相关的内容,强烈建议你同时去做工作里相关的这个任务。这是一个多赢的事情:

首先,你可以直接从项目维护者那里学习经验。然后呢,万一你遇到什么问题,你手中的项目可能得到“官方”支持。接下来,你应该不会觉得吃惊 – 项目维护者其实很在意大家的用例。另外就是假如这个项目开发新API的话, 你可以成为这个API的早期尝试者,在这个阶段如果你提出基于你公司用例的客观需求的话是很可能被考虑进来的。

当然,最重要的还是你个人的成长。你可以成为你团队里这个小领域的专家,我觉得这比你的工作时长更能够体现你的资历。

讲了这么多,下次要是有人找文档贡献,你会是这个前排举手的赫敏吗?

相关资料

最后,让我来分享一些相关资料。

如果你有意近期尝试一些文档贡献,我这里有一个库汇总了一些我自己觉得有所收获并且维护人很在意文档贡献的库:wgao19/well-maintained-docs

如果大家有了解更多的有同样精神的库,可以PR加进来。

英文资源

另外,下面是一些关于英文写作的资源,真的非常短,你可以在后面读一些我个人的推荐原因:

Rachel Andrew 是我非常喜欢的技术作者,CSS工作组成员,也是Smashing Magazine的编辑。我非常喜欢她的演讲和写作,这个CSS Tricks播客和她的访谈,观点都非常接地气,有时间的话推荐大家听一听。

Nicely Said 是基于我们领域的一本写作风格的书。它比较全面地介绍互联网写作的要领,语言简明易懂,可以很快读完,可以作为第一本书上手。

On Writing Well 是关于通适写作的参考书,语言非常幽默,观点犀利,也是很好读。

Good Prose 是个人最喜欢的一本,是一位普利策获奖者和与他常年合作的编辑的共笔。这本书的内容和我们领域的写作关联不大,但是关于写作、定位、组织内容等探讨得非常深入,算是一本进阶读物吧。


就这么多,讲完了,谢谢。

编辑于 2019-10-24

文章被以下专栏收录

    作为前端开发者的一些笔记,用中文写,可能包含想法和参会体会比较多,技术博客还请大家参考 https://aworkinprogress.dev/