如何设计良好的技术项目文档结构
前言
很多技术同学在日常的工作中接触到的大多是TO C的业务或者对外业务，由于大多数企业的主要营收是来自外部用户，因此内部的一些项目不会有太规范的流程和太高的要求标准。什么高可用高性能都是扯淡，良好的用户体验根本不存在。如果是一些内部的技术项目，特别是一些基础技术设施的技术项目，反而对技术要求是比较高的。
我目前在基础架构团队负责内部技术项目的一些工作，包括产品设计、交互逻辑、撰写PRD、项目管理以及测试工作。
这篇文章，想和大家聊聊，技术项目中一个良好的文档结构如何设计。
思维导图
一般来说技术项目可以分为四大阶段，本篇文章我会从四个阶段分别来介绍，在不同阶段需要设计哪些项目文档。
项目管理
无论是TO C的外部业务需求迭代还是内部的技术项目，项目管理是必不可少的事情。这里我想介绍下面三点我个人认为在项目管理中比较重要的点。
流程规范
流程规范相关的话题，我在之前的文章《测试工程师的职场发展二三谈》中做了很长篇幅的描述，这里再次重温下。
问：流程是什么？为什么要有流程？流程能解决什么问题？流程能带来什么保障？
流程是什么？ 流程是保障团队目标达成的最佳实践，因人/团队/业务类型/迭代速度/资源紧张程度而异。 为什么要有流程？ 没有流程会导致团队中的个体各自为战，目标不统一，进度不协调，资源配给失衡而导致交付质量下降。 流程能解决什么问题？ 流程能保障团队或者群体在大方向上保持协调一致，尽可能降低由于团队人员能力、认知水平、资源不足、意外情况导致的项目延期或者质量下降。 流程能带来什么保障？ 流程可以保障你可以有底气的据理力争，虽然不一定能扭转局势，但在一定层面上，会哭的孩子有奶吃，偶尔学会受委屈给领导看，也是以退为进保障自己利益不受太多损失的技巧。 流程规范的价值：风险可识别+问题可追踪+结果可验证+数据可量化！ 写博客的老张，测试工程师的职场发展二三谈
上面引用了之前对流程规范的一些描述，在具体的项目管理中，常见的流程规范有如下几种：
- 需求评审流程
- 方案评审流程
- 功能提测流程
- 发布变更流程
- 信息同步流程
- 项目复盘流程
迭代记录
目前在我负责的项目中，采用的是敏捷迭代机制，每周都会交付一个版本，可以是新功能上线，也可以是功能优化。
敏捷迭代模型的核心是快速交付可用的质量有一定保障的产品，让用户给到反馈和建议，不断迭代，不断满足用户新的需求，直到最终交付一个比较成熟的技术产品。
这种模型比较适用于内部或者需求不明确的项目；如果是需求明确对质量有高要求的，反而不适合这种迭代交付模式。而迭代记录，是将每次迭代的内容，通过小的内部版本号进行记录。它的作用有两点：
- 记录每次交付内容，向上有交代，对外有信心（即领导知道你在做什么，用户知道你再不断满足他们的需求）；
- 定期复盘的素材，通过定期复盘迭代交付过程的内容，找到做的不好的点，避免在后续迭代中犯错踩坑；
会议记录
一般这种内部技术项目，流于形式的务虚内容可以尽量减少，但下面两点我个人觉得是很有必要保留和执行到位的。
进度追踪：内部宣讲形成习惯，每天更新今天的进度，遇到的问题风险，评估是否需要调整优先级和迭代计划；
周报汇总：虽然说写周报我个人觉得是个很智障的事情，但这也是一种管理手段。我们不能祈求所有人都具备良好的职业素养和较高的自觉性，只能通过一些流程规范去尽可能降低和避免带来的问题。而且，周报也是向上管理的重要方式！
四大阶段
启动阶段
项目概述：即为什么做这个项目？背景是什么？要解决什么问题？面临哪些风险？项目的价值是什么？
项目规划：长期规划是什么？分几个阶段实现？每阶段重要产出物和里程碑是什么？如何量化评估每个阶段的交付物？
设计阶段
原型图：即这个技术项目的web页面或者后台管理页面，交互逻辑等。
需求调研：一般内部的技术项目，需求大多来自内部其他部门或团队。在设计阶段尽可能多的进行需求访谈是很重要的一件事。多去听用户的痛点是什么，他们想要什么，然后将用户需求转化为产品需求。
PRD文档：PRD是需求的最终产出物，有了PRD才能开展后续的如需求评审、架构设计等工作。
研发阶段
研发阶段实际上要做的事情是很多的，下面列举几项比较重要的需要产出的文档。
架构设计：架构设计即项目的技术实现方案，包括功能架构图、系统技术架构图、环境配置、各项参数等重要信息说明。
接口文档：接口的作用是约定数据的交互逻辑和出入口，也是功能联调和测试阶段需要重点关注的对象。
测试用例：没有一个产品是不需要测试验证的，测试用例的最大作用是验证产品实现是否是按照预期设计来实现的。
BUG列表：记录问题的本质，是梳理和复盘产品不足之处，并快速加以改正。
交付阶段
交付阶段即项目的线上发布，我个人认为下面2个文档是很有必要的。
使用手册：见文知意，使用手册的最大作用是帮助用户可以快速熟悉并使用起来。当然还有一个作用，避免用户没得看而导致不断询问你各种问题，你可以甩给他使用手册，培养他学习使用的能力，降低自己的对线压力。
接入文档：因为是内部的技术项目，部分功能需要业务或者用户接入或者做一些配置上的变更。接入文档作用是赋能用户去做变更，而不是项目的技术同学去帮他们做变更，这也是节省资源的一种方式。
附：相关工具
项目wiki：飞书文档
原型图设计：墨刀
架构图设计：ProcessOn
接口管理工具：Swagger
这篇文章主要内容是介绍技术项目中比较重要的文档结构，以及对部分文档的作用做一个简单的说明，仅供参考。
后续我会和大家聊聊，技术项目落地交付以及交付质量的一些事情，敬请期待。