10 - 互联网公司如何沉淀技术文档

Posted by 叉叉敌 on November 6, 2021

毕业之后在一家台企上班,属于制造业,当时候内部没有什么文档管理网站,都是用比较古老的方式来管理。比如 ppt、word,或者 svn 来管理文档,这个缺点就是没有索引,不利于搜索,找一个东西只有全凭记忆,甚至是运气才能找到自己要的资料,更别说是更新文档。甚至有时候找到的文档里面的解决方案十分落后,不能解决当前的问题。

后面进入互联网方面,比起上一家公司,文档沉淀方面是一个质的飞跃。也有相对完善的管理和更新,比如大家熟知的 confluence,以及现在大家都喜欢用的语雀、飞书。

目前所在公司用的 confluence, 这个工具有很多好处,比如授权、迁移、更新、父子页等。但是缺点也有,就是针对某个工具或者代码片段没有具体的说明,没有上下文看起来比较费劲。如果直接把代码片段贴在文档里面也不是不可以,但是维护起来就不方便。

上次在 Q3 季度面谈中,和领导沟通了关于文档沉淀的问题。个人揣测,老板认为文档沉淀根本没啥用,因为很少用人后期会去看文档,所以只有简化流程,让项目变得简单易做,才不需要文档。包括后面项目交接、离职交接等,文档沉淀个人觉得是目前最好的保障。

最近在 dev.io 看到一篇文章,提高谷歌、推特等公司是如何管理文档,只要是技术文档。

来看看 TensorFlow 里面嵌入的 g3doc 文档。

我非常认同的是,文档写作或者制作起来要简单,标准化和固化流程,已经文档可以维护和更新。

开源的解决方案也有了,Sphinx 是一款 python 文档生成工具,轻松创建智能美观的文档。

Python 官方的文档就是用这个工具生成的,语法有点类似 markdown,也很简单。

如果你的公司文档工具不好用,或者公司刚刚起步,可以试试这一款工具。


儿童到底每天喝多少牛奶

我家小朋友所在学校,目前供应的是一款 250ml,每 100ml 含 3.1g 蛋白质,每天 2 瓶。

部分好多家长觉得这款牛奶的含蛋白太低了,估计受到广告的蛊惑,比如电视广告里面提到的,有些高达 3.8g 蛋白质,家长朋友们要求更换牛奶。

  1. 10岁左右的孩子,每日摄入蛋白为40g左右,优质蛋白占14%, 6g左右。目前新希望的一瓶200ml*3.1/100=6.2g,完全足够;

https://new.qq.com/omn/20191007/20191007A04W7500.html

  1. 蛋白不只是牛奶才有。蛋白质主要来源于动物性食物如肉、蛋、奶和部分植物性食物如豆类、谷类;

  2. 牛奶最重要的作用是促进骨骼发育,里面含有铁元素、维生素,尤其是钙。

https://www.betterhealth.vic.gov.au/health/healthyliving/milk

看了一些文档,就我个人的观点,牛奶每天 2 瓶就够了。还有一个为了降低「风险」,不要喝同一款、同一个厂商牛奶。可以每隔一段时间,换一种牛奶喝,自己也买过不同牌子的来喝,再推荐几个小众品牌,小西牛(蓝瓶)、麦趣尔、百菲酪(水牛纯奶)、欧亚,个人觉得还不错。

[推荐工具]

Blankly

前不久 A 股连续 49 个万亿成交量,最后被国庆节打断了,有机构估计,这里面量化交易占据 20%。

为股票、加密货币和外汇快速构建和部署量化模型,Blankly 是一个优雅的 Python 库,用于简化的方式与加密货币、股票和外汇进行交互。现在,不再需要阅读 API 或努力获取数据。Blankly 提供了强大的功能集,针对速度和易用性进行了优化、更好的回测和最终更好的模型。

Chome recording

在 Chome97(目前是95) 里面提供了一个Recorder Panle 功能,记录用户的操作流程,并且可以回放他们。

  • 可以添加断言功能
  • 还可以进行性能分析

如果你是从事过 WebUI 自动化的话,就知道这个功能非常有用,用来回归测试就非常的方便。

书或者电影

思考时刻: 懂得很多道理,依然过不好这一生。 那问题是啥喃?

  • 脱不花的「沟通的方法」 - 10%
  • 莫言的「蛙」- 30%
  • 电影「中国医生」- 100%
  • Derek Sivers的「How to live」 https://sive.rs/h

今天是坚持分享:第 10/30 天。