今日思考：前端技术文档内容应该是什么，怎么写，维护难点，如何改进，目前的行业最佳实践是怎样的，有什么工具可以利用？
内容应该是什么
前端开发常见的文档，大概有这些：
- 组件库，如何使用
- 框架库，api 用法
- README，通常是介绍项目工程化流程
这些是给用户看的，给技术看的文档像api接口文档，也比较好写，按接口来注释就可以。满足不了前端文档的要求。
假设:
- 前端有7、8个同事，
- 共同开发一个庞大的后台系统，
- 包含十几个大的模块，我负责其中的4个模块，订单、库存、发运、工单
现在我要走了，新同事接手我的模块，他最需要的是什么，或者说我期望他能从文档上看到什么？
- 新人需要知道我负责的这几个模块在整个应用中的位置，一般一个系统是为了解决一个事情，系统越复杂，这件事需要的工序或流程越多，所以要搞清楚负责的模块就得知道它在应用中的哪几步
- 我做过的业务，基于什么需求开发的，最好有需求时间线和相关开发（如果是做SaaS的，也应该注明相关企业）
- 遇到某些 bug 的 hack 方案
- 我写的这个函数是干嘛的
- 封装了哪些公共函数可以用（造了哪些轮子）避免重复，浪费工时
- 积累的一些经验，比如需要哪些配置，如何快速定位问题
对上面的 6 点，逐个捋一捋，
- 流程公司肯定有，给用户看也一样，应该算使用手册，跟前端没关系
- 这个最好由产品出个业务文档，需求是他提的，改动也是他改的，
- bug 收集，这个挺有用，但是对常出现的 bug 要想想原因，能不能一次性改好
- 语义化命名或者简短注释就搞定了，如果函数太臃肿可能违反单一职责原则，可以拆一拆，把工具方法提出去，要是拆不了代码分段给些注释，没必要写到文档里
- 这个可以按照框架 api 给出文档，建议自行分类放在 utils 目录下，每个方法给出注释，利用工具把注释生成文档
- 配置和经验可以写，一些繁琐的、重复的配置再考虑下自动化或者工程化、这也是系统优化的方向。
这么看下来，好像只需要写 3、5 和 6，再换个角度想下，新人要上手的步骤，接到关于模块新的需求和 bug 时怎么处理？
-
需求，新的业务不用管，老的业务他需要找到代码上下文，了解之前的业务，基于这个业务和需求去改动。这个过程的关键是老的业务在代码中的体现是否足够内聚
-
功能 bug，快速定位，熟悉业务，明确责任，甩锅或者自己改，同样需要熟悉业务
总结
本来想捋一下内容是什么，结果把怎么写和维护难点都挖出来了，再总结一下：
文档内容：bug 收集、配置、问题定位经验、工具函数
维护难点：工具函数的注释要随着代码变化而变化
如何改进：
- 倒逼产品，让他们出下需求文档和产品使用手册，各种管理系统技术文档难以产出的很大原因是开发拆不开业务和工具方法，错把业务当文档产出，导致更新不及时，产出没人看
- 对技术要求也高，代码尽量遵从设计模式，工具函数、异常捕获、埋点、API调用代码封装、提取出来，让业务代码同步、易读，对组件和函数起名也遵从语义化，更容易理解。
- 业务和一般方法拆开之后，再利用 JSDoc 对 api、工具方法对改动较小的函数按注释生成文档
- 对开发过程中重复、繁琐、易错流程考虑工程化优化，
工具： JSDoc
最佳实践：希望各位大佬给予补充
最后，能看出来前端文档其实也是众多函数的 api 文档，但是最好平时在开发结束就维护文档，别在员工要离职了紧急扔个文档。
