前言

我从2021年开始编写前端开发设计文档至今，粗略数了数，已经有60+篇文档。

这期间，从文档标题到文件分类都有了细微的变化。

• 文档标题上：我和上线单的标题对齐了，如何可以区分版本的，我会加上当期版本。
• 文件分类上：我区分了业务场景分类，方便快速找到某一期的需求。
• 文档内容上：最开始主要包含三个方面：任务拆分、功能设计、开发排期。随着经验的积累以及对他人经验的学习，我在设计文档的内容上做了升级，下面会详细介绍到。

这些变化和调整的最终目的，是为了阅读设计文档的人，能够更精确的了解当期设计重点，以及清楚全部的任务，进而帮助我更好的评估开发时间。

我最近阅读了一篇大佬写的文章，有了新的感悟，并在最新的一期的设计文档中做了局部调增。再加上最近翻阅之前的文档，总结了几点经验。

年末了，正好汇聚成一篇文章，跟大家分享交流一下。

为什么能坚持编写设计文档？

我之前曾经写过一篇《大型业务项目中，前端如何撰写设计文档》的文章，其中有关于「为什么推荐写设计文档」的部分。

之前着重阐述了“为什么推荐写设计文档”这个话题，主要是围绕着“任务拆分”和“代码设计”这两个方面。

诚然，这两个方面是重中之重。但是随着业务的复杂化，迭代的快速化，只关注这两个方面显然不能满足全部场景，为了更好的应对挑战，编写设计文档，成为了开发前的必经之路。

更好的应对挑战，也是我能坚持编写设计文档的主要原因。

接下来，我来理一理开发路上都有哪些挑战。

文档写得好，排期才能快、准、稳

1、通常RP里，越是一句话的需求，越要打起十二分精神。

比如某期中，下面这个需求，甚至都没有直接体现出来新增之后的使用场景。

于是，开发问了一句“新加的类型怎么用”，便有了接下来的1/4任务。

设计文档的任务拆分，应对遗漏开发和遗漏排期的良策也。任务拆的对，少走至少5个工时的弯路。

2、想要代码质量好，功能说明同样重要

功能说明（也可称为功能描述）可以将原本复杂的流程化繁为简。

业务散的满天星，文档把它聚成一团火

1、RP也不是无所不能的，偶尔口头的需求或者群里确定的功能点，还是得靠设计文档才能把功能点记录的明明白白。

比如下面这种情况，如下截图，需求是将现有的「是否用户订单」改成「订单方式」，同时枚举值也一并更新。

看上去没什么难度，但是其实忽略了一点，就是原来的枚举值是：是和否。

于是我们便在业务群里确认这一点。

看对话时间，还好是今年10月份的，如果更久的聊天记录，找起来就十分麻烦了。

而我一般找功能，会先看代码的更新时间，我的更新记录中一般会带上当期版本信息。

我找到当时的设计文档，就能轻松的找到需求修改前后的对应关系。

总结就是，设计文档更的勤，陈年的芝麻好捡。

2、好记性靠不住，烂笔头才是真绝色

代码里有一个重新获取支付的功能，这功能的交互具体是怎么重新请求？要读会代码才能知晓。（当然直接加一段交互注释也不是说不行。）

但是，设计文档中标注好交互描述也是一个不错的选择。

3、随时随地，一键搜索任务关键字

工具往往有一些很便捷的功能，比如搜索。

如果我想找到某一期关于保司推送的功能，只需要搜索关键字，就 可以很方便的找到包含推送的开发设计文档。然后在进一步精准定位。

闲来读一读，温故而知新

偶尔翻阅之前的开发设计文档，读读之前的设计方案，有时候会新的灵感。子曰：“温故而知新，可以为师矣。”

年末的设计文档分享

《大型业务项目中，前端如何撰写设计文档》一文中，有一个章节专门介绍设计文档写什么，我重读一遍，发现写的略微宽泛，不够精炼，我重新总结一下。

Part1：相关文档

1、主要包括但不限于

当期需求的RP、当期需求的Wiki上线单、在线设计稿（非必需）。

2、当期需求的RP和当期需求的Wiki上线单

有时候RP不止一个，所以放到设计文档中，可以更快速便捷的找到。

3、在线设计稿（非必需）

Part2：任务拆分

1、主要包括单不限于

任务归属、任务细分、估算开发时间、里程碑（非必需）。

2、任务归属和任务细分

大部分前端任务都可以找到对应的操作界面。

3、估算开发时间

估算的开发时间时，我一般是以页面为估算维度，同时会依托于功能设计中的复用关系，以便排期更准确。

此外，对于交互，还需要在基础功能上，额外加上开发时间，一般会加20%~30%；对于UI，则需要单独评估UI还原的时间。

4、里程碑（非必需）

如下图是一个项目进度计划的甘特图，甘特图又叫横道图，是展示进度信息的一种方式，包含关键的里程碑。仅供参考。

注：里程碑对于大型开发还挺有帮助的，它标志着项目中的重要时刻，可以帮助开发者判断当前进度是否符合预期，如果有意外偏移，可以及时进行调整。

Part3：功能设计

1、主要包括但不限于

功能说明、实现方案、流程图、其他影响（非必需）。

2、功能说明

有时候功能说明总结出来了，实现方案也就八九不离十了。

比如支付优惠的设置，RP罗列的十分详细，一目了然。但是我们在做开发设计的时候，是需要进行归纳的。

这时候，功能说明就排上用场了。上面这个详细的表格，归纳成功能说明，就是下面的三句话，一目了然。

3、实现方案

实现方案可以帮助保障代码质量，同时也帮助前后端提前了解并确定数据的结构。最好包含功能实现的伪代码，有助于阐述逻辑。

上面支付优惠的伪代码：

/**
   * 通过不同订单和用户类型的优惠方式
   * @param {Object} param 订单和用户信息
   * @return {Array} 返回的支付优惠方式
   */
  getEmployerPayTypeListByData(param) {
    const { orderType, userType, configPayDiscountMap } = param;
    let payDiscountTypeList = configPayDiscountMap[orderType][userType];
    const customizedMap = {
      exclusive: 3, // 3-尊享优惠
      enterprise:4, // 3-企业优惠
    }
    // 如果用户类型是尊享用户或企业用户 优惠方式需要新增一种
    if (userType === 'exclusive' || userType === 'enterprise') {
      const customizedDiscountTyp = customizedMap[userType];
      payDiscountTypeList.push(customizedDiscountTyp)
      
    }
    return payDiscountTypeList;
  }

此外，对于复杂的功能，还会有多方面考虑，比如：某些复杂的交互，可能浏览器实际能实现的与产品预想的有偏差，这时候可以提供多个备选方案，供产品挑选。

而逻辑和UI的复用，我会在设计文档里面独立开辟一块内容，帮助了解哪些功能不需要重做，哪些可以为今后所用。

4、流程图

一般复杂的流程，产品原型里都会附上业务流程图。

但是对于前端来说，其实还有一个交互流程和业务流程图略有不同。

梳理清楚业务流程，方便编写功能说明和设计功能方案。如下是沪家保理赔的查勘任务交互流程图：

理清楚交互流程图，操作步骤也就明了了。

5、其他影响（非必需）

有时候，开发做代码重构的时候，会修改或删除一些旧代码或接口。这些改动，最好详细记录一下影响范围，方便测试同事帮忙测试。

Part4：上线配置

1、主要包括但不限于

页面权限配置、定制数据。

2、页面权限配置

一般对于第三方的页面是需要特殊的页面权限配置的。

3、定制数据

还有一些定制的数据，比如之前的特定的页面样式需要定制化，所以就需要定义清楚究竟有哪些数据是需要配置的。

总结

总结一下本文的核心内容：

• 编写技术开发文档，有助于开发者省时省力和保持质量的进行项目迭代。可间接帮助减轻延期风险。
• 开发文档的内容不是一尘不变的，除了推荐的内容，可以精益求精，根据需要添加可以帮助自己开发的内容项。

年末，能在对过去一年做一个简单的总结，怎么不算一种额外的收获呢。

最后，2024龙年，预祝大家，编程更顺利，技术更精湛。

作者介绍
非职业「传道授业解惑」的开发者叶一一。
《趣学前端》、《CSS畅想》等系列作者。华夏美食、国漫、古风重度爱好者，刑侦、无限流小说初级玩家。
如果看完文章有所收获，欢迎点赞👍 | 收藏⭐️ | 留言📝。