大家认为好的交接文档和形式是什么样的？

[yanjieee]

大家如果要从其他团队接手一些老的后端项目和组件，一般喜欢什么样的交接文档或者看过什么特别棒的“交接最佳实践”。 以下是我列出来的觉得可以呈现的文档或者手册：

• 组件当前的网络拓扑（包含主备、多活是什么样配置，每个节点的服务器信息）
• 组件用什么方式保活的（ systemd/supervisor ），组件如何升级的，升级是否会中断服务？
• 代码仓库各个分支的说明，以及如何进行 CI/CD
• 组件重要日志的目录在哪，字段的说明，有没有收集到 ES ？
• 组件涉及的所有第三方服务列表，对应的 key/license 是什么？

[28Sv0ngQfIE7Yloe]

可以再加上

日常运维流程

历史故障（坑）解决流程

迭代流程（思路）

[utodea]

这些文档尽量不要等到交接的时候再去写，而是应该在日常工作中去完成。同时也应该把这些文档当成项目或者仓库的一部分，放在 仓库 wiki 里随着项目更新而修改。这样不管是对新人还是工作交接都更有利于。

以下是我们团队的一些实践：
1.新手教程。
2.架构说明。各个组件的作用，核心依赖以及非核心依赖。国内、海外，主、备等。
3.组件介绍。每个组件的核心逻辑、核心目录等介绍，可以根据重要程度详细或者简略介绍。
4.编码实践。如何搭建本地环境、分支管理策略、issue/PR 规范、代码审核规范、单元测试规范。
5.运维实践-开发篇。如何预发布、灰度、发布、重启、回滚等，以及 CI/CD 。
6.运维实践-运维篇。云服务商依赖、基础设施依赖简介。监控：业务监控、基础设施监控，报警：业务报警、其他报警。
7.测试。 如何单元测试、本地集成测试、预发布环境测试。
8.日志。日志规范、如何使用日志。
9.故障与问题。历史故障复盘、常见问题如何处理。
10.非预期。限流、降级、预案等，最小集功能。
11.账号与 license 。 各种依赖的账号、license 应该去那里找。
12.其他：核心功能的设计讨论文档链接等等。


等到交接的时候再去写上面的这些内容，细节早就遗失了。

[AoEiuV020JP]

@utodea #2 可是交接文档残缺坑的是别人，维护文档麻烦的是自己，

[utodea]

@AoEiuV020JP #3 取决于怎么看待。抛开各种硬性、软性的好处。或许也可以参考一下另一种看法，即：技术文档是团队工程实践的记录，并且属于团队知识的一部分（而不是个人知识）。团队内的资深工程师和 Tech Lead 有责任维护它并进行更广泛的传播。

[AoEiuV020JP]

@utodea #4 取决于屁股，
如果我是 leader 我希望手下有及时维护更新文档，git 记住版本，
如果我是马仔我没有那个自觉在上头没要求的时候主动更新可能没人看的文档，

[forgottencoast]

@AoEiuV020JP 取决于一个人有没有不断努力提高自身能力的愿景。
你以为想把 @utodea 说的这些东西写出来，写做好是随便就能写出来的吗。
写文档也是需要能力的，优秀的专职文档工程师报酬也是很丰厚的。

从另外一个角度来说，公司招聘一个开发工程师开发软件，他的职责并不局限于开发新功能，2# 所列的这些文档——当然需要团队的实际情况来增减——有利于团队开发和维护工作，必然也属于工作职责之一。虽然这不是一个人的工作，但是必然应该由团队成员来完成。