查看原文
其他

手把手教你打造内部文档系统 | 红杉汇内参

洪杉 红杉汇 2023-04-26

[ 编者按 ]我们不时会在社交媒体的热搜上看到大型互联网公司服务器出现问题的消息。这些问题有的很快被修复,有的则需要用户等待许久。在抢修的过程中,比用户更焦躁的,就是计算机工程师了——他们不仅要追根溯源,找到问题从哪里来,还要与时间赛跑,反复多次调试新的代码;倘若半夜遇到服务器瘫痪,召集计算机工程师又要花费一段时间。


特别是,当丰富的经验、关键的知识都只留在了资深工程师的头脑里时,这个过程又会被延长。


其实这个问题,对于初创企业,尤其是技术性组织来说非常关键,是需要在起步阶段就需要注重的事情——打造内部资料系统文档,随时将任何有价值的知识和企业路线规划等信息记录下来,之后每个加入的新员工都能通过学习这些材料迅速适应角色,掌握关键资源,而不至于因为无经验而拖慢团队的步伐。


但是情况没有这么简单,特别是对于初创企业而言,相比于产品研发、品牌营销、用户拓展来说,人手不足、事项繁杂,“抽出时间整理经验并记录归档”就会变得微不足道、能省则省;而一旦放松,这些宝贵的经验就会随着时间流逝被遗忘。


如何处理这个问题?本文用四个步骤,手把手教你打造内部文档系统,并且让其在公司发展中发挥最大的价值。


每期监测和精编全球高价值情报,为你提供先人一步洞察机会的新鲜资讯,为你提供升级思维方式的深度内容,是为[ 红杉汇内参 ]

在一些技术性组织中,我们可以观察到这样的现象:早期的老员工们随着公司一起成长,他们对公司的基础设施、产品开发等极为熟悉,加上他们有着丰富的工作经验,新员工有任何问题都会第一时间寻求他们的帮助。久而久之,经验越丰富的员工就需要回答越多的问题,继而无法发挥自己的真正作用,去做具有更大回报价值的开发工作。

这就是公司没有总结内部文档,无法让经验形成可共享的文档所导致的。

但是,总结内部文档也不是一件简单的事情。你需要有人专门去推进,还需要这个主管人能够形成一套判断的标准;也不能让这项工作流于形式主义,比如有的公司对外的文档详细又规整,为客户提供了极为详细的产品介绍手册,但是内部的技术文档却一塌糊涂;另外,内部技术文档也不能过于“内部”,有时候需要其他公司的成功经验作为辅助借鉴,这样才能得到一部精要文本。

无论是初创企业,还是已经成型的大型组织,想要打造一个高效、全面的内部文档系统,都需要从文化转变开始,一步一个脚印。

第一步:从文化转变开始
文档方面的工作常常会落入一个十分尴尬的境地:觉得做了挺好,甚至很有必要,但就是一直腾不出时间来,但直到真的出问题了,才想起来它重要。

更关键的是,不但要做,而且一开始就要做好。试想,当你对着错误的经验手册修复错误,只会引起更糟糕的问题发生。

那么要招聘专人来执行吗?如果是初创企业,建议你从团队或企业文化着手,用小投入带来大影响。可以分为以下三个关键步骤:

1.树立良好的写作文化

要想把写作融入企业文化,最有效的方法就是确保从创始人到一线管理者,大家都能认真对待自己写的东西——要准确、高质量。具体写什么内容?你可以:

定期分享总结。对于管理者来说,可以写会议要点与后续跟进方案——管理者分享自己在会议上的记录要点与后续行动纲要,会激励其他人效仿。

靠近本质的思考。你最近学到了什么?你怎么看公司当前的目标?你们最近在战略上做了哪些调整?定期分享这些思考,不仅能让大家在思考时更注重决策的背景,也同时强调了写作与分享知识的重要性,这些都会慢慢渗透进组织文化当中。

2.养成编辑的习惯

有员工觉得自己不会写文章,怕写得不好被批评,所以会抗拒写作。这个时候,管理者的“编辑”角色就极为重要——要给他们提供具体的修改意见作为反馈,让他们逐渐习惯记录自己的工作;引导他们去阅读写得好的案例,帮助他们分析为什么写得好……总之,要鼓励他们多写多分享。

3.让写作成为工作晋升要求的一部分

很多领导者急于修复有缺陷的内部文档系统,会直接从战略入手,比如试图打造一个完美的内部流程,将文档纳入软件开发周期,或者换一个工具,希望如此便能解决问题。

但更确切地说,应该从更上游的地方开始抓:招聘和内部晋升体系。如果在招聘职位描述和内部晋升体系里就写明对知识共享的要求和期望,人们在代入这些角色的时候,就会自然而然倾向于把它当作份内事去做。

当你开始执行相关规定后,员工们必然需要一个具体的文档写作要求。以下是几个岗位层级的要求,供你参考:

初级工程师:做好代码相关的文档工作,如相应的代码注释和README文档。
高级工程师:做好服务和系统的文档工作,如相应的图表和端到端指南。
技术部管理:做好整个团队的文档记录与管理,落实从代码评审到事件评审的制度。

工作要求与绩效评估及岗位晋升挂钩后,员工便会优先考虑这方面的工作。在实际执行后,就会有人提出新做法来提升效率。比如建议在办公系统中集成一个可查的文档合辑,大家有什么问题一搜就能找到相关答案,这时你就可以不断改进你的工具和标准。别忘了将它综合进员工们的绩效考核中。

除了业绩考核方面,平时也可以有些鼓励积极性的做法,比如积极表扬每周在这方面做得不错的员工等。另外,还可以专门留出时间来共同研究怎么更好地实现文档,或者就这方面的贡献度做个排行榜,以此刺激大家。

第二步:发挥MVP员工的光和热
即使转变了文化,你可能还要面对之前的文档系统方面的问题,你要先处理好它们,才能推进下一步。

这件事情急不得,必须循序渐进,才不会“翻车”。首先要确定最关键的问题,你可以直接向工程师们发调查问卷,或者看看日常办公软件里被问得最多的问题是什么——可能你会搜集到100多个不同的反馈,但一开始,你必须先集中精力解决最迫切的5到10个。需要注意的是,不要自己去假设人们需要什么,你想的可能会和工程师们需要的完全不同。

有的放矢、先解决最关键问题的附加好处是,你会更快取得更有意义的进展,并开发出高质量的文档范本,供组织中的其他人参考效仿。

1. 设定标准时,要更注重质量

在一开始让工程师们做文档时,大多都会需要参考范本。所以,这时候就需要你将主要精力和资源都投入到撰写一份标准的黄金范本上,这样你们的整体水平也会逐步提高,体系也会在这个基础上搭建起来。

你还可以增加这两个方面的标准:代码标准和术语表。树立统一的代码标准,可以有效减少开发和代码评审所需的时间,并且你们的代码库也会高效规整得多;每个公司都有自己系统和服务的术语,所以非常有必要建立一个对应的术语库,来减少分歧。

2. 像记者一样去写

当然,相对简单的主题处理起来可以直截了当,但大多数的问题都很难找切入点。所以,你可以找一个真正的“技术权威”去替代各种技术备忘录、电子邮件、内部通讯软件上的信息碎片。

找那些经验最丰富的技术专家,和他们坐下来,一起在白板上列出相应的要点。如此,就有了文档的雏形,之后再相应分配对应的工程师去有针对性地细化。用不了多长时间,就能整理出一套可靠的、前所未有的技术文档。

同样的做法也可以应用到更复杂的文件编制工作中,比如服务器架构的搭建。优秀的文档写手就像记者一样——跟着线索脉络,填补空白,写出完整的故事。

3. 发挥资深工程师的作用

让团队某一个人来专门负责文档方面的工作的同时,还要充分发挥资深工程师的作用。他们一方面知道文档的重要性,但另一方面往往意识不到自己的影响力。所以,只要公司提供了平台,其他人就能跟着他们形成规范。

你可以先与高级工程师充分沟通,就如何建立一个更稳固的文档文化达成共识,然后持续对话来不断强化这些新的操作规范。比如在架构讨论和代码评审过程中,让高级工程师来负责强化文档操作规范。用不了多长时间,大家就会习惯这种新的规范,而不觉得是额外的义务。与此同时,新加入的成员也会相应遵守。

第三步:管理,让文件井井有条
养成记录的习惯只成功了一半。以一种有逻辑的、易检索的方式来组织你的文档则是工程团队面临的另一个重点。如果没有相应的管理系统,工程文档只会越积越多,最终混乱无序,无法分清哪些是最新的准确版本。

这些工作对很多团队来说可能有些难以推进,其关键在于找到一种人们可以便捷搜索过往资料的办法,然后建立体系,这要花费大量的时间和精力。但它却是四两拨千斤的好事,相对小的付出就能获得极好的效果,特别是那些本身还犹豫要不要投入人力物力去做文档系统的组织——先考虑文档系统的架构,而不是一上来就让大家写文档,可以在相对较短的时间内产生更广泛的影响。而且,这件事情本身并不涉及太多新的背景知识的学习,只需要清点现有的内容,合并重复的,删除过时的,清理和更新一些重要的,然后将它们规整成体系即可。

1. 整理清单

从组织的基本要素开始,把所有的重要文件都列出来,放到一个电子表格里。落到表格上会让一切变得更清晰,同时它也相当于一个目录,方便你之后把文件归档归类进内容库。

在这个阶段,你可以尽情按自己的想法去整理,哪些文件是多余的、哪些方面的内容还有空缺,以及是否可以规整出一个更好的结构等等。此外,你还可以将它发送给其他人,获取反馈,这比让大家各自整理要好得多。 

在搜集文件清单的过程中,可以留心以下五大类文件:

新员工培训文档。入职培训的文档可以为新员工提供有效的学习路径。随着团队的发展,要求每位新员工写下他们在最初几个月学到的东西。每次招聘新人就在之前的基础上继续完善知识体系。用不了几轮招新,你们就会拥有一份相对可靠的入职培训指南了。

操作指南类文档。例如,指导内部员工建立新节点、整合新界面或者使用新功能之类的说明性文档。

运行手册。比如如何以特定顺序执行一组任务,来完成诸如启动新服务器或解决常见错误之类的操作。

架构和设计文档。这是骨干文件,为所有其他文件和知识获取提供有用的背景信息,人们据此了解整个系统的工作逻辑。

团队百科类文档。包括会议记录、备忘录、思考、建议等。这些文档的记录可以随意一些,但注意与上述其它类型的文档区分开来。这些是团队快速获取和分享知识的非常宝贵的资源,但它们可能非常杂乱。

可能归整整个工程部门的各种文档到一个电子表格中难度太高、文件太多整理不过来,那不妨就整理一份前50个最常用的文件的清单,因为有总比没有好,即使是再简单的归类整理也会有好处。你也可以先整理最重要、最常用的那些文档,剩下的有空再慢慢整理。

2.确定责任人

很多时候,人们花费了大量的时间归整,记录了很多条理清晰、方便易用的文档,但却忽略了相当重要的一个部分:作者的名字。署名会让作者更重视、更负责,与此同时,当后期文档需要更新时,也能找到对应的责任人或团队。

你还可以开发相应的元数据标签,在上面署名团队或作者的名字,同时开发通知功能,定期通知文档负责人维护或评审文档的更新。而随着公司的发展,每几个月可能会有一次组织变动,到时可能会有新的团队名称,也需要做相应的维护,或者打造更复杂、自动化的系统亦可。

除此之外,为了让事情运转得更顺利,还需要指定一名专职或轮值的主负责人,不能是各部门或各组织的内容各自为政。如果每个团队自我负责的话,那大家可能就不太会在意团队间以及整个大集体的利益。

3. 敢于删除精简

想要保持文件系统规整,最重要的是让人们学会删除。冗余文件常常造成干扰,影响搜索效率。删除精简是为了让系统变得更高效,而且如果文件已经完全过时,弊就会大于利。

4. 做更好的目录页

电子表格文档整理做好之后,必须要制作目录索引,这件事情是小投入大回报的事情。当内部搜索引擎水平有限的时候,好的目录页就能发挥巨大作用。

第四步:将文档整合进开发周期
到目前为止,我们已经讨论了:通过补充欠缺的文档和调整文件系统结构来解决之前欠下的文档债的问题;降低检索和管理的难度。但要真正把这件事情做好,还需要调整习惯,让被动记录转变为主动记录与管理——也就是说,要在开发的同时就把文档编写好,而不是留到写完代码发布完之后。

但是,有时时间紧迫,代码都是在最后期限才完成,大多数团队就会把文档类的工作拖延到功能发布之后。但你要知道,总会有新的事情冒出来,你就会拖延着不去写文档,计划会永远赶不上变化。

与其在开发完成之后,面对着空白文档从头开始回忆做记录,不如在边开发的过程中,边留存快照记录。快照可以是操作截图——到时文档的使用者也可以参照的具体流程指引。早期阶段,这些快照文件可能杂乱无章,但却比事后回忆更准确。此时也还不需要补充什么背景信息,就如实说明使用者应该参考快照怎么操作、输入什么即可。

这种做法不仅能最终为你的团队节省大量时间,还能让你们少走弯路,做出更好的产品。比如你们的文档记录会更可持续,还可以不断迭代,在过程中,帮助你们更好发现一些平时可能没注意到的细节,了解产品在其生命周期的每个阶段都需要什么来取得成功。你开发产品的时候可能觉得整体的使用流程很简单,但如果你在过程中有做每一步的记录,最终当你发现,居然要25次操作才能获得一次结果时,你就知道你需要再做调整或精简,把它降到5次操作。


小贴士

#一年一度《科学》杂志评选新鲜出炉#
2022 Science年度十大科学突破
▨ 1.NASA新的詹姆斯·韦布太空望远镜(JWST)
今年,JWST终于张开了它的红外黄金之眼。通过它,研究人员发现了数千个新的星系,它们比以前记录的任何星系都更为遥远和古老;它能够收集足够多的从天体(从诞生中的恒星到系外行星)发出的光,从而揭示这些天体的组成以及它们在太空中的移动轨迹。这些数据已经开始以极为详细的方式揭示了距离地球数百光年外的各行星的大气组成,这将为它们是否可能以我们所知的方式支持生命提供线索。

▨ 2.惊人的巨型细菌
在法属安的列斯群岛的一片红树林沼泽中,一种单一的线状细胞在腐烂叶子的表面首次被研究人员发现。这个暂时被命名为Thiomargarita magnifica的微生物,比许多细菌细胞大5000倍,像一根图钉一样长,具有复杂的内部结构。

▨ 3.更易于耕种的多年生稻
中国的研究人员培育出的“多年生稻23”(PR23),是多年前由一种亚洲商业水稻品种和一种生长在非洲的多年生野生水稻杂交而成,经过20多年的研究,在今年产量和质量终于达到广适、高产稳产、多年生性强的标准。

▨ 4.黑死病如何改变欧洲人基因的新见解
今年,研究人员发现——黑死病的幸存者更有可能携带增强他们对鼠疫耶尔森氏菌(Yersinia pestis)免疫反应的基因变异。

在伦敦黑死病之后,大约有245个基因变异的频率上升或下降,其中ERAP2基因特别突出,它已被证明可以帮助免疫细胞识别和对抗威胁病毒。如今,45%的英国人体内仍然存在ERAP2的保护性变异。这种保护性基因变体在欧洲的快速传播是迄今为止人类基因组自然选择的最有力例子。

▨ 5.200万年前环境DNA重现古老生态系统
今年,科学家们在北极沙漠的冻土中成功提取了至少200万年前的微小DNA片段,其显示,那里曾有茂密的杨树、崖柏属和其他针叶树,还有黑鹅和马蹄蟹,以及驯鹿、旅鼠和乳齿象等哺乳动物。

▨ 6.RSV疫苗取得突破进展
呼吸道合胞病毒(RSV)对婴儿和老年人有着致死的威胁,因此针对这两个群体的疫苗研发一直在进行中。在突破种种研究困难后,RSV疫苗终于取得突破进展。今年已经进入了临床试验,并取得了良好的表现。

▨ 7.人类首次行星防御实验成功
在距地球数百万公里外,一颗被命名为迪莫弗斯(Dimorphos)的卫星千百万年来都在绕着另一颗更大的小行星旋转。9月26日,NASA用一枚航天器撞击了迪莫弗斯,永久地改变了它的轨道——同样的策略也可能在将来拯救整个人类文明,若在未来探测到环绕地球的小行星,使用这一方法可消除其带来的威胁。

▨ 8.美国通过具有里程碑意义的气候法
今年美国通过的《降低通胀法案》(IRA)中与气候有关的条款是其有史以来为减缓全球变暖所迈出的最大一步。该法案将在未来的十年向可再生能源与核能发电提供3690亿美元的资金、鼓励向电动汽车的全面转型并激励与减少工业排放相关的研究。根据一些独立研究团队的计算,它应该能使美国在十年后将其温室气体排放量降低到其2005年排放水平的40%。

▨ 9.创造性人工智能的快速发展
AI正向着原来被认为只属于人类的领域进军。从艺术领域的文本生成图像模型,到科学、数学以及编程领域,都有新的AI工具涌现。

▨ 10.发现可能导致多发性硬化的病毒
今年,研究人员利用大量的军事医疗记录,证明了一种常见的疱疹病毒在多发性硬化症(MS)中扮演着重要角色。这一发现可能会促成治疗或预防这种神秘疾病的新方法。

2023,从这条Flag开始

2023年就快来啦!


站在新年与旧岁的交点,又到了立Flag的时刻。作为各位读者成长路上的陪伴者,今年,【红杉汇】想给你一份辞旧迎新的仪式感,与你共同迎接新的一年,特此正式向你发起——


2023新年Flag征集令


2023,你想好要立哪些Flag了吗?本次征集主题、内容不限,无论是事业、学业方面的踌躇满志,还是健康、生活方面的“精致宣言”,抑或是爱情、友情方面的美好期待,都欢迎在留言区留言。


我们将精选并汇编部分读者的新年Flag,最终推出2023新年特辑,被选中的读者将获得由红杉汇赠送的精美新年礼品一份。


征集时间:2022.12.20-2022.12.27

征集方式:在本文下方留言处留言

征集内容:我的2023新年Flag

要       求:主题、内容不限,条理清晰,保证原创





推荐阅读




高质量识人选才 | Human Capital Talk第十二期

先听后说,是领导者的一种可贵品质 | 红杉七问之谈

斑布创始人沈根莲:造一张竹纸的变与不变 | 红杉爱生活

周期波动中的消费品牌如何蓄势勃发?| 2022红杉中国CEO峰会精彩回顾(5)

与AI技术同行的2023年 | 红杉汇内参

您可能也对以下帖子感兴趣

文章有问题?点此查看未经处理的缓存