开发忙的团团转，往往都是研发效能惹的祸：你真的会写README.md吗？

开发忙的团团转，往往都是研发效能惹的祸：你真的会写README.md吗？

大家好！我是老码农。

《码农说》公众号的第3篇文章暖暖来袭，接下来几篇我想从研发效能这个视角分享！

加班=研发

研发在团队中往往给其他团队的感觉，不加班不太正常，做研发的哪能不加班呢？

好像研发天生就和加班画上了等号。

这种观点是不对的，要改的。

研发加班原因很多，主要有

• 产品需求老变更
• 产品排期太紧
• 任务难，人员技术能力跟不上
• 。。。

的确上述的情况都有可能发生。

今天的分享只从研发团队内部的研发效能这个角度阐述观点，听起来有些拗口。

但实则很多时候研发团队内部的效能真的不敢恭维。

抬头看路

昨天阅读了一篇文章，文章的标题：埋头做事重要，抬头看路更重要，只有选对方向，努力才会有收获。

这句话重点我加粗了：抬头看路更重要，

当产品需求变更、排期紧等外部因素我们也争取了，但仍不可控的时候。

我们有没有尝试突破现有的思维，在我们内部提升研发效能，减少不必要的加班呢。

团队会写项目的README.md？

项目的README.md和研发效能也能挂上钩，是不是有点扯。

我们先看一个后端开源脚手架项目的截图

这是截图的一部分，这些内容都写在项目根目录的【README.md】文件中，我画框的几部分

• 项目简介：让团队成员能大致快速了解项目是做什么的？
• 系统模块：现在很多项目都是微服务，模块分的比较多，尤其新进入项目的人员，比较懵，这块介绍能让新人快速了解项目的构成。
• 每一个微服务的端口号在系统模块说明中写的也很详细，能让开发人员启动就知道占用端口是什么？

我们接着看, 下面这张是架构图，能一眼知道我们的项目都用了哪些技术。

继续看：

这块针对系统的访问做了详细的说明

• 访问URL
• 访问的账号

对比

没有对比就没有伤害，需要先问自己5个问题：

• 我们真的不需要一份完整【README.md】吗？

• 新人到团队能快速了解我们的项目吗？

• 新人到团队能快速搭建起来开发环境吗？

• 产品资料散落在很多位置，你能快速找到吗？

• 开发和测试环境的账号都有哪些？不同权限的用户你能网罗全吗？

先说新人

这四个问题里面尤其第2个问题：新人到团队能快速搭建起来开发环境吗？

谈谈我自己的感受，我个人也经历过外企、私企、大厂等多个团队。

我也跟团队里的小伙伴们聊过这个话题，大家的反馈基本一致，到一个新团队

• 搭建开发环境全都是靠嘴不断去问？
• 搭建开发环境很少能顺利，各种坑？
• 就没有一份完整的资料，包括常见问题如何解决？
• 。。。

总之，顺利的话，2天能跑起来开发环境，不顺利的搞的时间更长。

就拿搭建开发环境的maven来说，很多团队

• 有自己的私服，需要在setting.xml做配置；
• 有的团队会涉及一些付费的组建，这些组件往往下载不下来，或者下载不完整，导致代码编译过不去；
• 还有的团队，需要一些特殊的顺序才能变已过去，尤其微服务涉及各种jar包依赖关系；

这些一点手顺都没有，扔给一个新人搞，肯定会花费很大力气。

再说老人

之前刚进一个项目，这个项目用的工具很多，每次在各种工具、资料中来回切换，根本记不清哪些资料放哪里了？

不是我这样的新人痛苦，在团队中待很长时间的人也很痛苦，各种搜索，查找才能定位到。

没有梳理，大家都是瞎撞，这个研发效率能高吗？

所以呢：一份好的README.md能充分提高我们的研发效率。

README.md中写什么？

做项目最忌讳，项目做完了，东西全都在开发人员脑子中，没留下任何电子或者纸质的资料，遇到问题全靠问，人员一旦离职，全都麻爪。

针对开发工程我列个大纲，供大家参考。

（我一般在推进项目的时候比较注重梳理）

• 项目简介

  • 项目说明
  • 团队架构：便于相关团队对口的人

• 开发环境搭建手顺：这块一定要有，是个大坑点，没这个搭建环境就的折腾很长时间。

  • 软件位置？
  • 如何安装？
  • 各种软件的IP、端口、用户名、密码

• 产品资料位置

  • UI
  • 产品需求
  • 各种规范
  • 。。。

  如果涉及账号申请、拉群需要说明负责人

• 测试环境

  • 测试环境地址
  • 各种维度用户的账号、密码
  • 流水线的地址、具有流水线权限发布的人

• 技术资料

  • 日常汇总技术资料位置
  • 日常分享PPT资料位置
  • 生产事故点检分析报告
  • 。。。

• 。。。

后面就不一一列举了。

总结

一份好的【README.md】能让大家快速定位到自己想找的资料、想找的人。

大家不要小看这一点，相信大家尤其在构建开发环境这个环节深受其害，

各种问，各种查，各种郁闷，都源于一个团队没有一份完整的资料，

• 你自己调查，耽误自己时间；
• 你问别人，别人也没记录，也要回忆，帮你调查，耽误2人的时间；

而且如果团队人数很多，这个过程会不断重复。

我们写一份优美的【README.md】，不香吗？

我是老码农

大家好！我是老码农。今天就分享到这里。

关注《码农说》，期待用不同的视角与大家进行深入的交流，一同学习技术，提升研发效能，共同高速成长。