微医自研架构《EasyDoc》开源啦！

EasyDoc是什么

• WHAT：EasyDoc是一个易配置的降本提效的项目文档系统
• WHY：
  • 减低复杂项目的上手难度，提升用户体验
  • 抹平项目组新老人员信息差
  • 将项目的业务细节载体从开发者变更为文档工具
• HOW：通过流程用户引导、流程操作手册、页面说明文档、项目说明文档、关键点注解文档等方式实现
• 现状：EasyDoc已经在微医集团内部孵化一年多了，已经接入了十几个线上应用，正在集团内部全面推广中。同时向社区开源推广，希望能给社区带来一点新鲜的血液，期待大家的使用接入，有任何问题欢迎留言评论、或在github给我们提意见。
• 典型场景：管理后台、复杂表单、复杂流程、复杂交互😉😉
• 不适场景：大屏项目、游戏类项目🤣🤣

EasyDoc起源

先来看看一个故事

由上面的故事可以得出项目研发过程中的一些文档相关问题：

• 完整业务逻辑分散在原型图、bug系统、代码注释、人脑记忆中，不易检索、容易丢失，给项目的持续迭代带来了极大的可维护性成本
• 长期迭代开发的项目，只有开发者知道业务细节，新人根本接手不了。一旦开发或产品离职，业务逻辑随之丢失，交接文档根本无法起到太大作用。给项目研发带了极大的可控性风险
• 外部的操作手册PDF，由于重视程度不够、项目迭代频繁，总是忘记及时更新，沦为鸡肋。
• 即使有健全的文档，在流程具体的操作过程中也会遇到很多问题。用户体验很不好，并且要时常对用户或运营进行培训和24小时问题解答。如果有实时的用户引导或操作手册就好了。 others
• 只有粗略的项目背景介绍，没有页面介绍或模块介绍
• 没有用户引导或用户引导不统一，用法怪异，用户体验差
• 有操作文档，但多系统跳转的复杂操作无能为力
• 无人维护业务文档或维护成本过高

针对上述问题设计解决方案

• 项目文档：
  • 首次：在页面被第一次打开时弹窗向用户介绍一次当前系统的背景、目标、功能、注意事项
  • 更新：通过版本号控制的方式在实现项目文档更新重新弹窗一次
  • 回看：后续如果需要继续翻看文档可通过点击右上角EasyDoc按钮查看
• 页面文档：
  • 打开：点击右上角EasyDoc按钮才显示，弹窗查看当前页面的功能介绍和使用注意事项等
  • 更新：通过更新对应页面的json文件更新
• 页面关键点文档：
  • 打开：点击右上角EasyDoc按钮才显示，对页面某个关键的逻辑点做注解备注，方便用户或开发理解
  • 更新：通过更新对应页面的json文件更新
• 可编辑节点文档：
  • 打开：点击右上角EasyDoc按钮才显示，用于解决：’用户前台系统展示数据，后台系统编辑展示的数据的架构模式中，解决运营不知道去哪里修改前台展示内容的场景’
  • 更新：通过更新对应页面的json文件更新
• 用户引导：
  • 打开：调用EasyDoc的api进行操作，复杂流程使用用户引导进行傻瓜式教学，并结合步骤关键点文档进行注解加强理解
  • 更新：前端开发维护
• 操作手册：
  • 打开：点击右上角EasyDoc按钮打开，对多页面或多系统跳转的极复杂流程进行步骤化注解，让用户在页面上实时实地实景的看对应的操作手册，跟随操作手册一步步操作。
  • 更新：通过更新项目的操作文档json文件更新

EasyDoc视频使用演示

EasyDoc哔哩哔哩演示视频

EasyDoc技术选型变化及迭代

• 版本1 typesciprt+rollup+less+jest

  为了打包更小我们没有使用任何UI框架并使用rollup，没错，我们就是一群追求极致的年轻人😎😎，但这导致我们使用js编写html的时候吃尽了苦头ε=(´ο｀*)))唉。为了可维护性更好我们决定使用typescript，这确实提高了我们的代码质量，更重要的是使我们意识到代码质量的重要性。我们使用jest框架编写单元测试，这的确消耗了我们一些时间，但对于一个没有专职测试人员的架构项目，这样做非常有必要。单元测试极大的提高了自研项目的健壮性、可维护性、可用性、稳定性。

• 版本2 typescript+rollup+less+jest+vue2

  是的，我们使用vue2重构了js编写dom的代码，这不是因为vdom可以给我们带来性能的提升，这点性能对于现代浏览器来说根本不是瓶颈。主要是因为js编写dom的可维护性太低了😂😂，这也让我们深刻的体会到了三大框架对于前端开发的意义。

• 版本3 vue3+ts+element-plus开发可视化配置json插件(副包、暂未开源)

  我们发现由前端在public里编写项目的json文件的交互形式对前端同学确实不太友好，这无疑将业务文档的维护工作全权交给了前端同学。当时我们是这样考虑的🤔🤔：

  多年来前端由于不直接接触业务方和数据源，导致前端人员在项目组中充当开发资源没有地位没有思考没有发言权没有业务成长没有晋升机会；我们希望前端通过承担EasyDoc维护项目业务文档的方式来贴近、掌握、思考、反哺业务，提高前端在项目组中的地位和发言权，通过前端视角带给项目更多的价值增长。

  然而当我们去推广的时候，发现这种方式有一些弊端：1.产品、测试、后端同学没有前端代码权限没办法修改文档。2.前端维护全部文档的工作可能过重。3.部分前端并不想贴近业务也不需要贴近业务而我们不能强人所难。所以我们开发了可视化配置json文件的插件来解决这个问题。

• 版本4 lerna

  为了加速首屏渲染，我们尽可能的减小主包的大小，所以我们拆分了一些副包，这让我们的代码仓库过多。目前的开发人员稳定所以没什么影响，但开发人员频繁调整带来的仓库管理负担的隐患我们必须未雨绸缪提前解决😜😜。于是我们使用lerna将所有EasyDoc相关的代码聚合到一起，并统一管理授权和部署npm的工作。

EasyDoc技术实现方案思考过程

• 技术需求：我们需要给项目、页面、某个标签添加一段文字备注
• 技术诉求：我们需要建立强力的div和业务文档json的一一对应关系
• 解决方案1：使用博客网站常用的Xpath方案实现
  • 优点是对页面源码没有入侵性；文档和项目代码完全解耦；任何人都可以编辑修改非常方便
  • 缺点是如果页面源码修改了会导致Xpath失效需要重新添加，而且那些失效了也不知道，对于频繁迭代的项目来说维护文档简直就是灾难🤣🤣
• 解决方案2：使用vue指令+element tooltip做一个文档插件
  • 优点是dom借用了element能力不需要额外开发，文档就近存储在vue html里面非常简便利于理解和修改
  • 缺点是只能前端维护文档，太依赖vue和element通用性差，文档侵入性太强
• 解决方案3：使用标签自定义属性docId建立标签和json文档的映射关系
  • 优点是对源码入侵小，文档和源码解耦放在项目public文件夹里，后期通过可视化插件让所有人都能够轻松的编辑修改🤞🤞
  • 缺点是没有完全将文档和项目解耦；需要给标签添加docId还是有弱入侵性
• 集体讨论后决定使用解决方案3实现

通过docId建立html标签和json文档映射关系方案

EasyDoc代码组织架构图

架构自研项目推广迭代

• ✨试点运行很重要

  一个架构自研项目在上线之前是无法预测用户态度的，这个时候试点项目就非常有必要和价值了。通过试点项目观测产品的稳定性、易用性、用户使用姿势、用户学习成本等，可以在正式推广之后减少很多的风险和不确定性😊😊。

• 产品发布会

  通过一场正式的演讲来向全公司推广架构项目是一个非常好的途径，既能够有时间充分的讲述你的产品，又能够利用会议录屏回看功能来持续推广。还能和同学们现场进行思维的碰撞，收集同学们的思路灵感和意见来完善产品。不要害怕别人battle你，这是完善自身的一种非常有效的方式。

• 寻找潜在用户，好产品也要好推销

  机会不会主动来找你，你要主动去找机会。多和其他业务线的产品、前端、测试、后台聊聊业务文档的事情，倾听他们的吐槽、了解他们的痛点、共情他们的痛苦，顺势推出我们的产品并演示，趁热打铁拿下他；如果不能当天拿下，也要记录在案来日回访。

• ✨倾听用户的声音，不要反驳要及时响应

  用户并不在乎开发的技术实现细节和开发问题开发难点，用户只在意自己的痛点和什么时候能解决🤦‍♂️🤦‍♂️。不要反驳用户的使用姿势、思维方式不对，而是应该引导他或者迁就他的方式。你要知道：用户就是个只会嗷嗷叫的孩子他啥都不会，而我们的使命是让他用我们的产品用的舒服而不是用的嗷嗷叫。

  • 故事1：我们去找某个产品推广EasyDoc希望她能接入，她听完介绍后也觉得很好，但是回复业务太忙了，没有工期写文档接入。后来该产品的运营一直吐槽产品难用不会用，产品教的焦头烂额，想起了我们。自从接入了EasyDoc后，产品反馈流程问题吐槽、咨询少了一大半🤦‍♀️🤦‍♀️，沟通成本骤降了很多，用户体验非常好。自此之后她成了我们的忠实用户。
  • 故事2：EasyDoc右上角弹窗原先是hover状态下就会弹出的，同时很多应用用户名点击退出登录也在右上角，很容易误划到EasyDoc面板。我们跟用户解释为什么要做成hover弹窗出现？是为了节约用户点击的这一步骤，这是用户体验优化。但用户并不关心我们的优化点，用户只关心误划问题🤷‍♀️🤷‍♀️，当我们意识到我们的优化确实给用户带来了副作用时，我们决定去掉优化改成点击才弹窗。
  • 故事3：EasyDoc原本是弹窗后固定在右边的，同时很多后台系统的页面都有表格，表格操作按钮也在右边，所以我们的面板挡住了用户操作按钮，需要用户来回点击开关EasyDoc面板。这很不人性化，我们意识到了这个问题，并准备下个版本优化掉。但用户3天内多次询问我们什么时候改好，我们回复和其他优化一起在下个版本迭代掉。但在用户眼里，我们改个小问题太慢了而且用户并不关心其他的优化🤷‍♂️🤷‍♂️。当我们意识到这点后，在第3天晚上单独把这个需求拎出来修改发布掉了。
  • 故事4：EasyDoc操作手册原本是各自独立的，因为每个操作手册都是独立的模块单元。但是用户觉得应该可以一个接一个的看，或者彼此跳转看，甚至不同系统间的操作手册也可以关联起来跳转。我们非常想反驳用户你的使用姿势真是奇葩！简直是异想天开瞎搞乱搞🙌🙌。但是我们很有素质，我们认真考虑了用户诉求，重新定义了操作手册的操作方式满足了用户的痛点。用户真可爱。

• 用户的使用痛点就是迭代的目标和价值

  软件即服务，用户的痛点就是价值点，闭门造车是很难造出好产品的。

架构自研项目向上管理

• ✨价值和意义（降本提效、业务增长）

  探索、思考、总结、汇报自研项目对于公司的价值和意义是什么，让老板看到价值点才会给你更多的资源投入，你的产出才有意义。同时汇报项目的产品设计、竞品分析、可行性分析、难点解决方案，但不要替老板做决定，把最终决策权留给老板。

  EasyDoc通过承载业务文档来降低开发期间的检索成本、沟通成本、返工成本、交接成本，提高项目上手效率、掌握效率、开发效率；EasyDoc通过承载业务文档来降低用户使用期间的理解时间、探索成本、试错成本提高用户体验和用户留存率，促进业务增长。

• 对齐目标（预期管理）

  我们经常使用四象限时间管理法来对todo list进行优先级排序，但是我们经常忽略一个问题，同一个自研项目对于你的优先级和老板的优先级是不同的🤣🤣，这是因为我们考量的标准更多的是是个人技术和能力的成长，而老板考量的标准是“优先做对于公司更有价值的事”。所以我们需要在每次制定季度目标之前和老板对齐当前季度自研项目的目标。如果没有对齐目标这一步很有可能你既没有功劳也没有苦劳还要挨批浪费人力资源😒😒！。

• 要结果、有结果、拿结果（闭环思维）

  对于老板承诺的资源、依赖方承诺的资源，我们必须要结果；对于自研项目每个季度的目标，我们必须有结果，只有承诺履约老板才会继续支持你；对于投入了大量人力资源的自研项目，我们必须拿到预期的结果，即便你不在意个人的绩效，也要为团队其他成员考虑。

架构自研项目平行管理

• ✨为什么要平行管理？

  大型的架构自研项目都是团队协作开发的，互相之间可能并没有上下级的领导关系，而是全部平等的职级。这时候当意见冲突时很难达成一致，又没有人能够拍板一锤定音。如果每次有分歧就找老板决策，会让老板觉得小题大做太无能。这个时候平行管理就显得尤为重要，如果我们能充分发挥平行管理能力，争取虚线带领团队推进项目，对自己的领导能力有很大的提升，又能让团队取得很好的成果，何乐而不为呢？

  • 故事1：最开始我们聚在一起开会商量怎么做这个的时候，大家都很沉默，开会没有流程、主持、拍板人、会议记录，只有无尽的头脑风暴和battle，混乱不堪。当会议结束后我开始反思：为什么大家都这么厉害聚在一起却变得这么菜？😢😢最后我发现是因为没有虚线组长的角色！于是我开始试着去推动去承担去把控每一次会议，通过会前推演规划、会中掌控流程节奏、会后跟进落实任务，我们的会议开始变得高质高效。
  • 故事2：用户使用我们的产品的时候会零零散散的跟每个开发反馈问题，然后开发会有空的时候改掉。但是业务忙的时候会导致用户反馈长时间搁置无人处理。我们不能问责开发同学，因为人家在做业务；但我们的用户反馈无人处理也是事实。于是我们开始思考有必要建立用户反馈问题处理流程🤔🤔：
    • 1.通过多人协作文档收集记录用户反馈信息和开发信息
    • 2.给定开发人员、排期、进展并反馈用户
    • 3.当个人工期冲突或阻塞时及时协调其他开发跟进
    • 4.问题上线后及时验证并通知反馈用户记录修改反馈
    • 5.定期检查问题进度避免有人遗忘
    • 6.定期复盘问题及问题根因完善产品和研发流程

• 如何平行管理？

  ✨平行管理其实是全局统筹的能力。1.先对架构目标进行WBS拆分，已合理分配所有成员任务为拆分的颗粒度考量。要充分考量到团队各人的能力、意愿、任务量、能拿到的结果。2.开会讨论解决方案并分配任务，对于问题要先提出合理建议抛砖引玉发挥出所有人的主观能动性；对于分配任务优先各人意愿并保持平衡尽可能的给出任务分配建议和理由。3.让所有成员填写每项任务开发时间、完成时间，评估合理性并建议调整。4.在每个时间节点前关心下同学的进度并作出处理。5.每个大阶段完成后或遇到重大问题拉个会议集体复盘头脑风暴一下，对过去的失败进行总结，对未来的计划进行调整。

• 平行管理要素

  格局视野、主观能动性、owner意识、规划能力、换位思考、以德服人。。。

开发维护人员

• 李运通 😜😜
• 杨毅臻 😎😎
• 胡宁 ✌✌
• 焦传锴 😉😉
• 权明扬 😘😘
• 黄丹丹🤞🤞

向前走、别回头

当然目前开源的只是EasyDoc的冰山一角，我们的规划的未来全貌是：

• EasyDoc主包：加载面板和弹窗，动态加载其他SDK副包
• EasyDoc可视化配置副包：提供可视化新增编写json业务文档的能力
• EasyDoc源码和页面元素映射副包：提供点击页面div找到对应vue标签位置的能力
• EasyDoc用户行为分析反馈收集副包：提供收集用户行为和反馈意见的能力
• EasyDoc文档管理后台：提供存放和修改业务文档的能力，实现文档和项目完全解耦，最终建设成为集团文档的收录系统

通往成功的路从来都不是一帆风顺的，路上曲折坎坷却令人着迷。在EasyDoc架构自研的道路上，我们经历过一腔热血加油干的激情，也经历过自我怀疑没意义的低谷，既经历过老板用户的表扬创意非常好的鼓励，也经历过用户无情的吐槽真特么难用。我们能做的只有坚持不懈、化茧成蝶😎😎。当我们走完这段路程回头来看，还是很感谢这段经历带给我们的成长的。虽然我们的产品可能无法带给社区多大的帮助多大的声音，但是我们也希望以我们的经历带给大家一些启发和信心💖💖，启发同学们做成更优先的架构自研产品，给正在架构自研路上的同学们一点信心你们一定会成功的。向前走、别回头，路上春色正好，天上太阳正晴✌✌。

延伸阅读

• 微医自研架构《EasyDoc》使用教程
• 你不得不知的设计模式ts版
• 你不得不知的大厂问题复盘方法论
• 大厂代码重构最佳实践，你真的会代码重构吗
• 有必要掌握框架源码的细枝末节吗？
• 【vue3源码分析】讲透源码开篇

EasyDoc github地址

github.com/wefront/we-…

记得给我们点赞✨✨点个star哟🤞🤞（づ￣3￣）づ╭❤～