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

　　前言
　　对于如何让技术人员写好开发文档，这是一个很常见的问题。
　　本次不过多分享理论，而是通过分享我们团队新成员编写的第一份真正的开发文档，作为成例，给大家参考和借鉴。
　　对于新人，一开始就明确高标准、提高专业要求，是很有价值的。需求背景
　　有一天，有位YesDev的企业客户和我们提到：黄总，上次说的客户管理的流程下，手工选择发送【反馈信息】，方式为短信，企业微信，钉钉，邮件。四种方式的配置信息和客户管理进行关联配置。发送后有发送记录可以进行管理，检索和导出。发送内容可以根据需求自动生成。其中短信可以进行模板管理和分配，短信发送接口配置（建议阿里云短信）。
　　于是，我们产品经理整理并设计了以下的产品方案和PRD。
　　以下，则是对应的技术开发人员在完整需求开发的同时，编写整理的开发文档。内容包含：开发分支、单元测试、SQL数据库变更、核心流程的时序图、新增的API接口、单元测试覆盖率报告、新增的配置文件等。使用的研发协同工具
　　YesDev，一款更友好的研发协同工具。开发文档成例分享需求背景
　　用户需要一个可以管理自己客户及客户联系人的功能，并且在需求需要反馈时，可以选择发短信或者邮件进行通知仓库地址https：codeup。aliyun。comxxxxxxxyesinewyesinewwww。git使用的是codeup云效。后端开发分支mxhtest实现思路用户需要可以配置短信和邮箱服务的后台录入功能用户需要进行客户名单的管理，包括但不限于客户分组、客户管理、客户联系人等功能，并且对以上的功能可添加、编辑、删除以及查看前端需增加反馈功能模块，用户可以获取录好的客户名单，进行邮件短信通知，并且记录反馈通知信息用户可以查看某个需求的发送给客户的反馈列表，也可以在企业管理后台，进行发送反馈记录的查看和导出记录新增接口（基于PhalApi开源接口框架）Platform。CustomerCustomer。AddCustomer添加客户Platform。CustomerCustomer。AddCustomerContacts新增客户联系人Platform。CustomerCustomer。AddCustomerGroup添加客户分组Platform。CustomerCustomer。DeleteCustomer删除客户Platform。CustomerCustomer。DeleteCustomerContacts删除客户联系人Platform。CustomerCustomer。GetContactsListByCustomerId根据客户ID获取联系人列表Platform。CustomerCustomer。GetCustomerDetailLeftSideMenu客户详情页左边栏Platform。CustomerCustomer。GetCustomerGroupList获取客户分组列表Platform。CustomerCustomer。GetCustomerGroupOption获取客户分组选项，用于select标签Platform。CustomerCustomer。GetCustomerList获取客户列表（用于分组下的客户名单管理）Platform。CustomerCustomer。GetFeedbackContactsList发送反馈时用到的客户联系人列表Platform。CustomerCustomer。GetOneCustomer获取单个客户Platform。CustomerCustomer。GetOneCustomerContacts获取单个客户联系人Platform。CustomerCustomer。GetOneCustomerDetail获取单个客户详情（用于客户详情页）Platform。CustomerCustomer。UpdateCustomer编辑客户Platform。CustomerCustomer。UpdateCustomerContacts编辑客户联系人Platform。CustomerCustomer。UpdateCustomerGroup编辑客户分组Platform。CustomerFeedback。GetFeedbackList获取反馈列表（用于前端需求页面）Platform。CustomerFeedback。GetFeedbackListForAll企业后台获取反馈列表Platform。CustomerFeedback。GetFeedbackListForAllExportData反馈列表导出Platform。CustomerFeedback。GetFeedbackListForAllExportUrl企业后台获取反馈列表导出链接Platform。CustomerFeedback。SendFeedback发送反馈信息接口Platform。SmsSms。AddSmsConfig添加短信配置Platform。SmsSms。AddSmsTemplate添加短信模板Platform。SmsSms。DeleteSmsTemplate删除单个短信模板Platform。SmsSms。GetOneSmsConfig获取短信配置Platform。SmsSms。GetOneSmsTemplate获取单个短信模板Platform。SmsSms。GetSmsTemplateDetailByMoudleId根据短信模板ID和模块ID，来获取替换后的短信文本Platform。SmsSms。GetSmsTemplateList获取短信模板列表Platform。SmsSms。GetSmsTemplateListByOpen获取已开启的短信模板Platform。SmsSms。GetSmsTemplateParam获取短信模板变量列表Platform。SmsSms。SendSmsTest发送短信测试Platform。SmsSms。UpdateSmsConfig修改短信配置Platform。SmsSms。UpdateSmsTemplate更新单个短信模板Platform。CustomerFeedback。GetFeedbackList获取反馈列表（用于前端）Platform。CustomerFeedback。GetFeedbackListForAll企业后台获取反馈列表Platform。CustomerFeedback。GetFeedbackListForAllExportData需求导出Platform。CustomerFeedback。GetFeedbackListForAllExportUrl企业后台获取反馈列表导出链接Platform。CustomerFeedback。SendFeedback发送反馈信息修改的接口Platform。Notes。CreateNewNote添加新备注Platform。Notes。GetNoteListMoreInfo获取备注列表Platform。AppSiteConfigAppSiteConfig。AddOrUpdateAppSiteConfig添加app配置设置文件变更（基于PhalApi开源接口框架）configsms。php22dataphalapipro。sql101srcappCommonApi。php17srcbaseCommonSms。php70srcbaseCommonToolUtil。php67srcbaseCommonUrlUtil。php5srcbaseDomainAppSms。php73srcbaseDomainBase。php8srcbaseDomainCustomer。php348srcbaseDomainCustomerFeedback。php350srcbaseDomainNotes。php11srcbaseDomainSms。php2srcbaseDomainSmsConfig。php243srcbaseModelCustomer。php5srcbaseModelCustomerContacts。php5srcbaseModelCustomerFeedback。php72srcbaseModelCustomerGroup。php6srcbaseModelSmsConfig。php11srcbaseModelSmsTemplate。php11srcplatformApiAppSiteConfigAppSiteConfig。php6srcplatformApiCustomerCustomer。php218srcplatformApiCustomerFeedback。php150srcplatformApiNotes。php11srcplatformApiSmsSms。php184数据库变更（使用MySQL数据库）DROPTABLEIFEXISTSppsmsconfig；CREATETABLEppsmsconfig（idint（11）NOTNULLAUTOINCREMENT，accesskeyvarchar（255）NOTNULLDEFAULTCOMMENT短信服务商的accesskey，accesssecretvarchar（255）NOTNULLDEFAULTCOMMENT短信服务商的accesssecret，configstatustinyint（2）NOTNULLDEFAULT0COMMENT邮箱状态：1开启0关闭，adminidint（11）NOTNULLDEFAULT0COMMENT管理员ID，addtimedatetimeDEFAULTNULLCOMMENT创建时间，appkeyvarchar（100）NOTNULLDEFAULT公司标识，createdstaffidint（11）NOTNULLDEFAULT0COMMENT创建员工ID，PRIMARYKEY（id））ENGINEInnoDBDEFAULTCHARSETutf8mb4COLLATEutf8mb4generalciCOMMENT短信配置表；DROPTABLEIFEXISTSppsmstemplate；CREATETABLEppsmstemplate（idint（11）NOTNULLAUTOINCREMENT，smssignvarchar（255）NOTNULLDEFAULTCOMMENT短信签名，templatecodevarchar（255）NOTNULLDEFAULTCOMMENT短信模板Code，templatedetailtextCOMMENT短信模板详情，templatestatustinyint（2）NOTNULLDEFAULT0COMMENT邮箱状态：1开启0关闭，adminidint（11）NOTNULLDEFAULT0COMMENT管理员ID，addtimedatetimeDEFAULTNULL，appkeyvarchar（100）NOTNULLDEFAULT，createdstaffidint（11）NOTNULLDEFAULT0COMMENT员工ID，PRIMARYKEY（id））ENGINEInnoDBDEFAULTCHARSETutf8mb4COLLATEutf8mb4generalciCOMMENT短信模板表；DROPTABLEIFEXISTSppcustomergroup；CREATETABLEppcustomergroup（idint（11）NOTNULLAUTOINCREMENT，groupnamevarchar（100）NOTNULLDEFAULTCOMMENT分组名称，customernumint（10）NOTNULLDEFAULT0COMMENT分组下的客户人数（冗余），adminidint（11）NOTNULLDEFAULT0COMMENT管理员ID，addtimedatetimeDEFAULTNULLCOMMENT创建时间，appkeyvarchar（100）NOTNULLDEFAULT公司标识，createdstaffidint（11）NOTNULLDEFAULT0COMMENT员工ID，PRIMARYKEY（id））ENGINEInnoDBDEFAULTCHARSETutf8mb4COLLATEutf8mb4generalciCOMMENT客户分组表；DROPTABLEIFEXISTSppcustomer；CREATETABLEppcustomer（idint（11）NOTNULLAUTOINCREMENT，customernamevarchar（255）NOTNULLDEFAULTCOMMENT客户名称，customerlevelvarchar（20）NOTNULLDEFAULTACOMMENT客户等级，AE，groupidint（10）NOTNULLDEFAULT0COMMENT分组ID，feedbacknumint（10）NOTNULLDEFAULT0COMMENT反馈次数（冗余），customerstatustinyint（1）NOTNULLDEFAULT1COMMENT客户状态：1开启0隐藏，customerremarktextCOMMENT客户备注，adminidint（11）NOTNULLDEFAULT0COMMENT管理员ID，addtimedatetimeDEFAULTNULLCOMMENT创建时间，appkeyvarchar（100）NOTNULLDEFAULT公司标识，createdstaffidint（11）NOTNULLDEFAULT0COMMENT员工ID，PRIMARYKEY（id））ENGINEInnoDBDEFAULTCHARSETutf8mb4COLLATEutf8mb4generalciCOMMENT客户表；注意事项新增了。configsms。php，第71行。configsms。php新增模块客户反馈，需要在两个表配置权限INSERTINTOppoperation（id，project，path，title，whitelist）VALUES（440，platform，customer，主模块客户管理，NULL）；INSERTINTOppoperation（id，project，path，title，whitelist）VALUES（441，platform，customerlist，客户管理模块客户列表，NULL）；INSERTINTOppoperation（id，project，path，title，whitelist）VALUES（442，platform，customerdetail，客户管理模块客户详情，NULL）；INSERTINTOppoperation（id，project，path，title，whitelist）VALUES（443，platform，customerfeedback，客户管理模块客户反馈记录，NULL）；INSERTINTOppoperation（id，project，path，title，whitelist）VALUES（444，platform，serviceconfigsms，服务配置短信服务配置，NULL）；单元测试（使用PHPUnit）
　　邮件短信发送的时序图（使用ProcessOn等工具可在线制作UML）
　　最终实现的效果截图（在YesDev可免费体验和真实使用）
　　登录后选择你的研发团队，
　　在企业管理后台，录入客户信息，
　　配置短信通道和通知文案，
　　最后，在前台可以进行邮件通知反馈，
　　也可以进行短信的通知反馈。