大家如果要从其他团队接手一些老的后端项目和组件,一般喜欢什么样的交接文档或者看过什么特别棒的“交接最佳实践”。 以下是我列出来的觉得可以呈现的文档或者手册:
1
28Sv0ngQfIE7Yloe 330 天前 via iPhone
可以再加上
日常运维流程 历史故障(坑)解决流程 迭代流程(思路) |
2
utodea 329 天前 7
这些文档尽量不要等到交接的时候再去写,而是应该在日常工作中去完成。同时也应该把这些文档当成项目或者仓库的一部分,放在 仓库 wiki 里随着项目更新而修改。这样不管是对新人还是工作交接都更有利于。
以下是我们团队的一些实践: 1.新手教程。 2.架构说明。各个组件的作用,核心依赖以及非核心依赖。国内、海外,主、备等。 3.组件介绍。每个组件的核心逻辑、核心目录等介绍,可以根据重要程度详细或者简略介绍。 4.编码实践。如何搭建本地环境、分支管理策略、issue/PR 规范、代码审核规范、单元测试规范。 5.运维实践-开发篇。如何预发布、灰度、发布、重启、回滚等,以及 CI/CD 。 6.运维实践-运维篇。云服务商依赖、基础设施依赖简介。监控:业务监控、基础设施监控,报警:业务报警、其他报警。 7.测试。 如何单元测试、本地集成测试、预发布环境测试。 8.日志。日志规范、如何使用日志。 9.故障与问题。历史故障复盘、常见问题如何处理。 10.非预期。限流、降级、预案等,最小集功能。 11.账号与 license 。 各种依赖的账号、license 应该去那里找。 12.其他:核心功能的设计讨论文档链接等等。 等到交接的时候再去写上面的这些内容,细节早就遗失了。 |
3
AoEiuV020JP 329 天前
@utodea #2 可是交接文档残缺坑的是别人,维护文档麻烦的是自己,
|
4
utodea 328 天前
@AoEiuV020JP #3 取决于怎么看待。抛开各种硬性、软性的好处。或许也可以参考一下另一种看法,即:技术文档是团队工程实践的记录,并且属于团队知识的一部分(而不是个人知识)。团队内的资深工程师和 Tech Lead 有责任维护它并进行更广泛的传播。
|
5
AoEiuV020JP 328 天前
|
6
forgottencoast 327 天前
@AoEiuV020JP 取决于一个人有没有不断努力提高自身能力的愿景。
你以为想把 @utodea 说的这些东西写出来,写做好是随便就能写出来的吗。 写文档也是需要能力的,优秀的专职文档工程师报酬也是很丰厚的。 从另外一个角度来说,公司招聘一个开发工程师开发软件,他的职责并不局限于开发新功能,2# 所列的这些文档——当然需要团队的实际情况来增减——有利于团队开发和维护工作,必然也属于工作职责之一。虽然这不是一个人的工作,但是必然应该由团队成员来完成。 |