创业CTO来分享如何让技术人员写好开发文档？

　　前言
　　对于如何让技术人员写好开发文档，这是一个很常见的问题。
　　本次不过多分享理论，而是通过分享我们团队新成员编写的第一份真正的开发文档，作为成例，给大家参考和借鉴。
　　对于新人，一开始就明确高标准、提高专业要求，是很有价值的。需求背景
　　有一天，有位YesDev的企业客户和我们提到：＂黄总， 上次说的客户管理的流程下，手工选择发送【反馈信息】，方式为短信，企业微信，钉钉，邮件。 四种方式的配置信息和客户管理进行 关联配置。 发送后有发送记录可以进行管理，检索和导出。 发送内容可以根据需求自动生成。 其中短信可以进行模板管理和分配，短信发送接口配置（建议阿里云短信）。＂
　　于是，我们产品经理整理并设计了以下的产品方案和PRD。
　　以下，则是对应的技术开发人员在完整需求开发的同时，编写整理的开发文档。内容包含：开发分支、单元测试、SQL数据库变更、核心流程的时序图、新增的API接口、单元测试覆盖率报告、新增的配置文件等。使用的研发协同工具
　　YesDev，一款更友好的研发协同工具。开发文档成例分享需求背景
　　用户需要一个可以管理自己客户及客户联系人的功能，并且在需求需要反馈时，可以选择发短信或者邮件进行通知仓库地址https://codeup.aliyun.com/xxxxxxx/yesinew/yesinew_www.git 使用的是codeup云效。后端开发分支mxh_test实现思路用户需要可以配置短信和邮箱服务的后台录入功能用户需要进行客户名单的管理，包括但不限于客户分组、客户管理、客户联系人等功能，并且对以上的功能可添加、编辑、删除以及查看前端需增加反馈功能模块，用户可以获取录好的客户名单，进行邮件/短信通知，并且记录反馈通知信息用户可以查看某个需求的发送给客户的反馈列表，也可以在企业管理后台，进行发送反馈记录的查看和导出记录新增接口（基于PhalApi开源接口框架）Platform.Customer_Customer.AddCustomer 添加客户Platform.Customer_Customer.AddCustomerContacts 新增客户联系人Platform.Customer_Customer.AddCustomerGroup 添加客户分组Platform.Customer_Customer.DeleteCustomer 删除客户Platform.Customer_Customer.DeleteCustomerContacts 删除客户联系人Platform.Customer_Customer.GetContactsListByCustomerId 根据客户ID获取联系人列表Platform.Customer_Customer.GetCustomerDetailLeftSideMenu 客户详情页左边栏Platform.Customer_Customer.GetCustomerGroupList 获取客户分组列表Platform.Customer_Customer.GetCustomerGroupOption 获取客户分组选项，用于select标签Platform.Customer_Customer.GetCustomerList 获取客户列表(用于分组下的客户名单管理)Platform.Customer_Customer.GetFeedbackContactsList 发送反馈时用到的客户联系人列表Platform.Customer_Customer.GetOneCustomer 获取单个客户Platform.Customer_Customer.GetOneCustomerContacts 获取单个客户联系人Platform.Customer_Customer.GetOneCustomerDetail 获取单个客户详情(用于客户详情页)Platform.Customer_Customer.UpdateCustomer 编辑客户Platform.Customer_Customer.UpdateCustomerContacts 编辑客户联系人Platform.Customer_Customer.UpdateCustomerGroup 编辑客户分组Platform.Customer_Feedback.GetFeedbackList 获取反馈列表(用于前端需求页面)Platform.Customer_Feedback.GetFeedbackListForAll 企业后台获取反馈列表Platform.Customer_Feedback.GetFeedbackListForAllExportData 反馈列表导出Platform.Customer_Feedback.GetFeedbackListForAllExportUrl 企业后台获取反馈列表导出链接Platform.Customer_Feedback.SendFeedback 发送反馈信息接口Platform.Sms_Sms.AddSmsConfig 添加短信配置Platform.Sms_Sms.AddSmsTemplate 添加短信模板Platform.Sms_Sms.DeleteSmsTemplate 删除单个短信模板Platform.Sms_Sms.GetOneSmsConfig 获取短信配置Platform.Sms_Sms.GetOneSmsTemplate 获取单个短信模板Platform.Sms_Sms.GetSmsTemplateDetailByMoudleId 根据短信模板ID和模块ID，来获取替换后的短信文本Platform.Sms_Sms.GetSmsTemplateList 获取短信模板列表Platform.Sms_Sms.GetSmsTemplateListByOpen 获取已开启的短信模板Platform.Sms_Sms.GetSmsTemplateParam 获取短信模板变量列表Platform.Sms_Sms.SendSmsTest 发送短信测试Platform.Sms_Sms.UpdateSmsConfig 修改短信配置Platform.Sms_Sms.UpdateSmsTemplate 更新单个短信模板Platform.Customer_Feedback.GetFeedbackList 获取反馈列表(用于前端)Platform.Customer_Feedback.GetFeedbackListForAll 企业后台获取反馈列表Platform.Customer_Feedback.GetFeedbackListForAllExportData 需求导出Platform.Customer_Feedback.GetFeedbackListForAllExportUrl 企业后台获取反馈列表导出链接Platform.Customer_Feedback.SendFeedback 发送反馈信息修改的接口Platform.Notes.CreateNewNote 添加新备注Platform.Notes.GetNoteListMoreInfo 获取备注列表Platform.AppSiteConfig_AppSiteConfig.AddOrUpdateAppSiteConfig 添加app配置设置文件变更（基于PhalApi开源接口框架）config/sms.php                                   |  22 +++ data/phalapi_pro.sql                             | 101 ++++++++++ src/app/Common/Api.php                           |  17 +- src/base/Common/Sms.php                          |  70 +++++++ src/base/Common/ToolUtil.php                     |  67 +++++++ src/base/Common/UrlUtil.php                      |   5 + src/base/Domain/AppSms.php                       |  73 ++++++++ src/base/Domain/Base.php                         |   8 +- src/base/Domain/Customer.php                     | 348 ++++++++++++++++++++++++++++++---- src/base/Domain/CustomerFeedback.php             | 350 +++++++++++++++++++++++++++++++++++ src/base/Domain/Notes.php                        |  11 +- src/base/Domain/Sms.php                          |   2 +- src/base/Domain/SmsConfig.php                    | 243 ++++++++++++++++++++++++ src/base/Model/Customer.php                      |   5 +- src/base/Model/CustomerContacts.php              |   5 +- src/base/Model/CustomerFeedback.php              |  72 +++++++ src/base/Model/CustomerGroup.php                 |   6 +- src/base/Model/SmsConfig.php                     |  11 ++ src/base/Model/SmsTemplate.php                   |  11 ++ src/platform/Api/AppSiteConfig/AppSiteConfig.php |   6 +- src/platform/Api/Customer/Customer.php           | 218 +++++++++++++++++++++- src/platform/Api/Customer/Feedback.php           | 150 +++++++++++++++ src/platform/Api/Notes.php                       |  11 +- src/platform/Api/Sms/Sms.php                     | 184 +	 数据库变更（使用MySQL数据库）  DROP TABLE IF EXISTS `pp_sms_config`;   CREATE TABLE `pp_sms_config` (     `id` int(11) NOT NULL AUTO_INCREMENT,     `access_key` varchar(255) NOT NULL DEFAULT ＂＂ COMMENT ＂短信服务商的access_key＂,     `access_secret` varchar(255) NOT NULL DEFAULT ＂＂ COMMENT ＂短信服务商的access_secret＂,     `config_status` tinyint(2) NOT NULL DEFAULT 0 COMMENT ＂邮箱状态：1-开启  0-关闭＂,     `admin_id` int(11) NOT NULL DEFAULT ＂0＂ COMMENT ＂管理员ID＂,     `add_time` datetime DEFAULT NULL COMMENT ＂创建时间＂,     `app_key` varchar(100) NOT NULL DEFAULT ＂公司标识＂,     `created_staff_id` int(11) NOT NULL DEFAULT ＂0＂ COMMENT ＂创建员工ID＂,     PRIMARY KEY (`id`)   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT = ＂短信配置表＂;     DROP TABLE IF EXISTS `pp_sms_template`;   CREATE TABLE `pp_sms_template` (     `id` int(11) NOT NULL AUTO_INCREMENT,     `sms_sign` varchar(255) NOT NULL DEFAULT ＂＂ COMMENT ＂短信签名＂,     `template_code` varchar(255) NOT NULL DEFAULT ＂＂ COMMENT ＂短信模板Code＂,     `template_detail` text COMMENT ＂短信模板详情＂,     `template_status` tinyint(2) NOT NULL DEFAULT 0 COMMENT ＂邮箱状态：1-开启 0-关闭＂,     `admin_id` int(11) NOT NULL DEFAULT ＂0＂ COMMENT ＂管理员ID＂,     `add_time` datetime DEFAULT NULL,     `app_key` varchar(100) NOT NULL DEFAULT ＂＂,     `created_staff_id` int(11) NOT NULL DEFAULT ＂0＂ COMMENT ＂员工ID＂,     PRIMARY KEY (`id`)   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT = ＂短信模板表＂;    DROP TABLE IF EXISTS `pp_customer_group`;   CREATE TABLE `pp_customer_group` (     `id` int(11) NOT NULL AUTO_INCREMENT,     `group_name` varchar(100) NOT NULL DEFAULT ＂＂ COMMENT ＂分组名称＂,     `customer_num` int(10) NOT NULL DEFAULT 0 COMMENT ＂分组下的客户人数（冗余）＂,     `admin_id` int(11) NOT NULL DEFAULT ＂0＂ COMMENT ＂管理员ID＂,     `add_time` datetime DEFAULT NULL COMMENT ＂创建时间＂,     `app_key` varchar(100) NOT NULL DEFAULT ＂公司标识＂,     `created_staff_id` int(11) NOT NULL DEFAULT ＂0＂ COMMENT ＂员工ID＂,     PRIMARY KEY (`id`)   )ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT = ＂客户分组表＂;    DROP TABLE IF EXISTS `pp_customer`;   CREATE TABLE `pp_customer` (     `id` int(11) NOT NULL AUTO_INCREMENT,     `customer_name` varchar(255) NOT NULL DEFAULT ＂＂ COMMENT ＂客户名称＂,     `customer_level` varchar(20) NOT NULL DEFAULT ＂A＂ COMMENT ＂客户等级，A-E＂,     `group_id` int(10) NOT NULL DEFAULT 0 COMMENT ＂分组ID＂,     `feedback_num` int(10) NOT NULL DEFAULT 0 COMMENT ＂反馈次数（冗余）＂,     `customer_status` tinyint(1) NOT NULL DEFAULT 1 COMMENT ＂客户状态：1-开启 0-隐藏＂,     `customer_remark` text COMMENT ＂客户备注＂,     `admin_id` int(11) NOT NULL DEFAULT ＂0＂ COMMENT ＂管理员ID＂,     `add_time` datetime DEFAULT NULL COMMENT ＂创建时间＂,     `app_key` varchar(100) NOT NULL DEFAULT ＂公司标识＂,     `created_staff_id` int(11) NOT NULL DEFAULT ＂0＂ COMMENT ＂员工ID＂,     PRIMARY KEY (`id`)   )ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT = ＂客户表＂; 注意事项新增了./config/sms.php，第71行 ./config/sms*.php  新增模块客户反馈，需要在两个表配置权限INSERT INTO `pp_operation`(`id`, `project`, `path`, `title`, `white_list`) VALUES (440, ＂platform＂, ＂/customer＂, ＂主模块 - 客户管理＂, NULL); INSERT INTO `pp_operation`(`id`, `project`, `path`, `title`, `white_list`) VALUES (441, ＂platform＂, ＂/customer/list＂, ＂客户管理模块 - 客户列表＂, NULL); INSERT INTO `pp_operation`(`id`, `project`, `path`, `title`, `white_list`) VALUES (442, ＂platform＂, ＂/customer/detail＂, ＂客户管理模块 - 客户详情＂, NULL); INSERT INTO `pp_operation`(`id`, `project`, `path`, `title`, `white_list`) VALUES (443, ＂platform＂, ＂/customer/feedback＂, ＂客户管理模块 - 客户反馈记录＂, NULL); INSERT INTO `pp_operation`(`id`, `project`, `path`, `title`, `white_list`) VALUES (444, ＂platform＂, ＂/service-config/sms＂, ＂服务配置 - 短信服务配置＂, NULL);单元测试（使用PHPUnit）
　　邮件/短信发送的时序图（使用ProcessOn等工具可在线制作UML）
　　最终实现的效果截图（在YesDev可免费体验和真实使用）
　　登录后选择你的研发团队，
　　在企业管理后台，录入客户信息，
　　配置短信通道和通知文案，
　　最后，在前台可以进行邮件通知反馈，
　　也可以进行短信的通知反馈。