精华内容
下载资源
问答
  • 2020-09-23 16:45:21

    此方案针对后台管理系统类,新增表单字段特别多的情况,如下
    在这里插入图片描述
    这里大概有三四十个字段,如果一个的对着接口文档来写异常耗时,就是个苦力活,那有没有什么办法可以实现快速生成这种简单的代码呢?我们的接口文档用的是Swagger
    在这里插入图片描述
    可以看到其实接口文档上对应的中文名和字段都是有的了,其实只需要把这个格式解析出来,然后循环一下就可以了。我们的接口文档有一个复制文档功能,复制出来是markdown文档,是这个样子的,我们只需要把表格部分复制出来解析就可以了。
    在这里插入图片描述
    下面是实现的方法

    var { Extractor } = require('markdown-tables-to-json');
    
    let md = `
    
    | label         | 请求类型     |     required |  type      |  --   |  --  |
    | ------------ | -------------------------------- |-----------|--------|----|--- |
    | fAreaId  | 大区id,整数类型 |   body    |   true   |integer(int64)  |       |
    | fCaptainTel  | 车长电话 |   body    |   true   |string  |       |
    | fCarsetCaptain  | 车长 |   body    |   true   |string  |       |
    | fCarsetCaptainId  | 车长id,整型 |   body    |   true   |integer(int64)  |       |
    | fCarsetDeputy  | 副车长 |   body    |   true   |string  |       |
    | fCarsetDeputyId  | 副车长id |   body    |   true   |integer(int64)  |       |
    | fCompanyApprove  | 公司特批:有特批,无特批 |   body    |   true   |string  |       |
    | fContractDesc  | 合同说明 |   body    |   false   |string  |       |
    | fContractName  | 合同名称 |   body    |   false   |string  |       |
    | fContractSituation  | 合同情况 |   body    |   true   |string  |       |
    | fCustomerCity  | 城市 |   body    |   false   |string  |       |
    | fCustomerId  | 客户id,整数类型 |   body    |   true   |integer(int64)  |       |
    `
    
    // 这里只写了一个input如果想更细致些,可以自己写判断来处理
    function input(label,code){
      return`
        <el-col :span="6">
              <el-form-item label="${label}" prop="${code}">
                <el-input v-model="form.${code}"></el-input>
              </el-form-item>
            </el-col>
            `
    }
    
    
    let mdData = Extractor.extractObject(md);
    let html = ''
    
    for(let key in mdData){
    	 html = html + input(mdData[key].label,key)
    }
    
    console.log(html)
    

    打印出来的效果,自己再放到页面中做一些调整就可以了
    在这里插入图片描述

    更多相关内容
  • 如何写前端技术方案文档?

    千次阅读 2021-12-26 00:27:35
     收集版本开发的相关文档,这样开发的时候只要通过这一个前端技术方案文档,就能找到所有的文档,有时候我也会把这些网页整理到一个浏览器书签文件夹里。 第三章,任务拆解。 主要描述开发任务归属、预计工时,...

    ce3dab6169639e153b276dba6a2723a3.png

    大厂技术  高级前端  Node进阶

    点击上方 程序员成长指北,关注公众号

    回复1,加入高级Node交流群

    前言

    百度百科对计算机软件的的定义为:“计算机软件( Software,也称软件)是指计算机系统中的程序及其文档,程序是计算任务的处理对象和处理规则的描述;文档是为了便于了解程序所需的阐明性资料。程序必须装入机器内部才能工作,文档一般是给人看的,不一定装入机器”。

    可以看到概念里提到了"文档",说明写文档是软件开发过程必不可少的一个环节,如果文档没有写好,那么软件也不能算是优秀的软件。

    可对于一般软件开发人员来讲,写代码要比写文字容易得多。很多时候我们都能看到类似的事情,项目做完了,设计文档还没有;当别人问起,某个功能当时为什么这么设计,一时语塞;项目代码里没有注释,时间长了,自己都忘记当时代码为什么要这么写;当接手别人的项目的时候,要排查个问题只能一行行读代码,唯一的文档就是随脚手架自动生成的 README.md。以上这些都是我们平时开发中可能会遇到的问题,为什么会这样?其实就是因为平时没有写文档的习惯,文字没有得以保留,只靠记忆,时间长了确实记不住。

    下文就想和大家一起探讨一下,前端为什么写技术方案,怎么写前端技术方案。

    写技术方案目的

    在讲为什么要写前端方案文档前,先讲一个我的好朋友小明的故事。

    小明也是一个前端,在接到需求的时候,他会大致看一下需求文档,感觉没有什么太大的问题,然后就看看交互、视觉稿上有哪些页面,接下来就开始迫不及待地写代码了。

    新建一个文件、写模板、写样式、写交互逻辑,一气呵成。新模块的需求是小明最喜欢的,因为不用去理解其它功能的逻辑,可工作中还是少不了维护历史代码。小明很聪明,他发现有个功能加个参数传过去做个逻辑判断就能实现,于是他也就这么做了。

    开发完后,小明觉得很满意,因为很快就实现了需求,代码在脑中的逻辑比较清晰,里面也许有些地方写的不太妥当,但是也无妨吧。虽然不是全局最优的,但可以说是局部最优的。

    版本提测之后,QA 开始针对各种边界问题和极端场景给小明提 bug。譬如输入框输入 emoji 表情后提交接口报错、按钮连续点击触发了多次请求、买家角色页面展示正常但是供应商角色展示错误……

    在改 bug 的过程中小明渐渐带上了痛苦面具,代码逻辑被改的支离破碎,不得不为代码打各种补丁,方法的参数加了一个又一个,逻辑里的条件判断加了又加。到这个时候小明的开发积极性已经被消磨的差不多了,开始对 QA 提出的 bug 表示质疑,他会用“原来就是这么设计的呀”、“这个问题不在这次的需求范围内”等等这样的说辞来避免对代码的更改。

    过了一段时间,小明又接到一个需求,需要对上次开发的模块增加一些功能。翻开代码的时候,小明整个人都崩溃了。以前代码的逻辑自己早就忘记了,面对自己已经看不懂的代码,开始对自己进行灵魂拷问“这个方法有什么用?这个方法怎么有这么多参数?为什么逻辑这么复杂?”,“代码在不同页面之间跳来跳去,还有长得几乎一模一样的代码,他们的逻辑到底是什么样的?”,“为什么会有这么多标识位,这么多魔法数字,他们都是干嘛的?”。注释什么的是不存在的,即使存在,也不明白在讲些什么。

    刚接手项目的时候小明还不断吐槽之前开发的人不写文档、不写注释,没过多久小明也成了别人口中的那个"他"。

    以上故事根据真实事件改编。

    我觉得写技术方案文档是能解决小明的一部分问题的,“谋定而后动,三思而后行”,都是在说这个道理。当然写文档也不是万能。对比一下后端,会发现他们在写代码之前都会做方案设计,好像难道后端的开发时间很充裕或者说前端的技术方案不值一提吗?肯定不是。方案设计是软件工程里的一个最佳实践,通常做技术方案的过程中会体现出软件整体的架构,当对核心流程梳理完成之后,最后基本都能落实到代码上。也就是说好的技术方案能体现出最后代码的逻辑,通过看方案就能知道代码怎么写。这样就防止了在写代码过程中边写边改,最后导致代码结构混乱的问题。

    怎么写技术方案

    如果我们按照后端那一套方法论和模板来做前端方案设计,发现根本写不出来什么内容,这时候我们要重新审视方案设计的套路,来发现前后端的不同。

    业务模型可能前后端都是一致的,毕竟我们是解决同一个业务问题。但其中也有稍许差别,前端有些数据不是从后端获取的,或者说不一定非要从后端获取,这点我们需要在做设计的时候考虑进去。譬如同一个 H5 页面在微信公众号内和钉钉内需要展示不同的主题色。

    前后端对于核心流程的定义也不同,对于后端来说核心流程是数据的产生、流转、消费,但是提到流程,在前端来说更多的是页面的流转、组件的交互、用户的操作。同样一件事情,在前后端来看完全是两个东西,比如保存一项数据,后端需要关注的可能是如何校验、如何存储、如何索引、如何关联。但前端要关注的却是校验接口的出入参、校验结果的展现形式如何、是跳转还是覆盖或者弹窗、不同屏幕和设备下如何适配。

    后端更注重逻辑架构与部署图,因为后端需要为服务化,服务间边界的定义要非常清晰、具体。前端与微服务对应的,应该就是组件了,但是组件覆盖的范围太广,从一个按钮到一个页面都可以称之为组件,甚至现在比较火热的微前端中的一个子应用也可以成为一个组件,所以前端的组件需要被划分成页面、模块、控件等不同封装层次的单元。在这个划分的过程中,逻辑架构自然体现出来了。同时前后端解决的问题不同,导致关注点也不同,前端需要关注页面的还原,比如页面的元素应该如何抽象,样式应该如何复用,这个是后端不用考虑的。

    接口可不仅仅是 http 请求,任何与其它模块交互逻辑都应该明确其入参和出参。后端需要关注暴露出去的 dubbo 或者 http 接口,因为这体现了系统间交互的逻辑。而对于前端来说对应的也应该明确独立模块或者页面之间的交互逻辑,所以也就需要明确这些"接口"。

    关于实施方案,前后端的关注点也有稍许不同,后端更关心系统之间的集成,旧数据的兼容。而前端应该关心的是桌面设备和移动设备的区别,或者微信、支付宝等不同渠道的集成。

    对比之后前端技术方案的脉络渐渐清晰起来。结合上面的方法论,下面就实际案例讲解一下。

    技术方案的案例

    ba93825b1e9731c804351ea922781a6c.png

    在政采云产研团队的研发流程中,前端方案设计是在需求和交互评审之后、测试评审和正式开发之前,属于需求阶段开发阶段的中间节点。此时需求的功能和用户交互场景基本已经确定,前后端技术方案之间互相补充描述清楚需求的可行性、整体架构和具体实现。同时在测试分析之前,也是帮助 QA 梳理测试重点和用例场景。

    第一章,概述。 一般会简单描述项目的背景和价值,做一件事情的意义或者说动机是很重要的,一般从需求文档里进行概括即可。然后解释后面文档中需要用到的一些专有名词,达成大家对一些名词的共识是很重要的。

    第二章,相关文档。 收集版本开发的相关文档,这样开发的时候只要通过这一个前端技术方案文档,就能找到所有的文档,有时候我也会把这些网页整理到一个浏览器书签文件夹里。

    第三章,任务拆解。 主要描述开发任务归属、预计工时,还有里程碑。

    估时是按照页面维度,拆分页面内主要功能,进行时间估算,时间估算按照静态 demo 和 JS 交互来分别评估会准一些。之后得出时间乘以一个 1.3 的系数(因为每周还会有不同的会议、沟通也会占用时间)。

    时间评估的时候,像下图一样,本地花点时间列一下 —— 这样的好处是一便于统计和比对,看有无遗漏;二评估出的时间,给到业务方、PM 等,会对我们有职业化上的认可——会认为这样的评估粒度,时间是准确的你这个人是靠谱的;另外,细粒度的维度,也便于业务方寻找需求最长路径,看需求或者走迭代也方便做出判断。

    f245ef90162273f07d675dedc77c4ba5.png

    第四章,总体设计。 列举开发规范,还有逻辑架构。一图胜千言,有关时序的逻辑强烈建议用图来代替。流程图、时序图、状态图,让你的技术方案文档逼格满满清晰明了。

    df3e4bb668e6499fd83397a1dd1363f0.png

    下图为页面跳转逻辑图,如果交互有缺失的话,前端技术方案里可以进行补位

    d60b42e8dd92091724bb47170b9d2d80.png

    第五章,详细设计。 这一章就是整篇技术方案的重点了,包括功能说明、流程说明、模块详细设计、外部依赖等四个小节。

    最完美的状态,就是如下图所示,这一部分写完了,代码也跃然于纸上了。

    3644451f6d5a05889be0b3d86f4850c9.png

       也可以适量地贴一些代码,可以很好地在技术分析的时候阐述清楚改动点

    9f02ab8c95bb9aa6b0e2c7c3c0359dd5.png

    下图为下单流程卡券选择时序图。复杂的时序逻辑已经不是文字能说的清的了,时序图让交互更清晰

    77b50ceb465f25435eec870ef22428b3.png

    下图为前端组件入参设计的案例,开源组件库写的都不错,可以直接参考。

    eefa9a7fa4726e6dbc58f2ca8b183f12.png

    最后三章可以写一写技术分析 Checklist、测试数据、遗留问题

    de05ed8ece0c583d2ce7b1f6c791a1b4.png

    最后附上政采云前端团队的前端技术方案模板,戳这里 (https://staging-gov-open-doc.oss-cn-north-2-gov-1.aliyuncs.com/1072PT/339900/10006126128/202110/dfa4e4a2-8b3c-4372-b002-9d6f701d5f40)。当然大家也可以根据自己的情况进行内容的增删,譬如我们原本是在技术方案里维护发布的 CheckList,但是后端也维护了一个,我们就索性建了一个公用的文档,归档在一起。

    最后的最后推荐两个好用的画图工具:

    • plantuml (https://plantuml.com/zh):使用简单的文字描述画 UML 图

    • drawio (https://www.draw.io):在线图标绘制网站 上面两个工具都有对应的 vscode 扩展。(processon (https://www.processon.com) 也挺好用的,可惜免费版只能存 9 个图表)

    Node 社群

    我组建了一个氛围特别好的 Node.js 社群,里面有很多 Node.js小伙伴,如果你对Node.js学习感兴趣的话(后续有计划也可以),我们可以一起进行Node.js相关的交流、学习、共建。下方加 考拉 好友回复「Node」即可。

    c5d0abe39d982a8c5e67e831c55a57de.png

       “分享、点赞、在看” 支持一波👍

    总结

    首先得承认一个事实,写文档和写作一样是一件很费时费力的事情,为了画一个流程图、为了斟酌一个词语,可能就会纠结好久。其次文档是需要持续更新的,不是技术评审开完就封版了,视觉评审、测试分析评审、后续迭代都有可能影响技术方案,需要实时跟进。如果能把产品各个版本的技术方案文档进行整合,甚至能得到整个产品技术方案的全貌。

    欲速则不达,很多人觉得技术方案是在延长开发周期,其实在政采云的落地过程中发现,技术方案设计的越详细,对质量提升,和维护成本降低效果明显,拉开很长周期来看,是加快了迭代周期。

    李开复老师在《浪潮之巅》的序言中说到:“我认识很多顶尖的工程师,但具备强大叙事能力的优秀工程师,我认识的可以说是凤毛麟角”。表达是软件开发工程师重要的软实力之一,作为软件工程的最佳实践,方案设计在前端开发过程中还是十分必要的,那么为什么前端领域长时间不注重这个事情呢,我觉得有以下原因:

    • 方案设计依赖技术能力,而前端技术栈变化太快,今天的设计套路放在明天可能就失效了;

    • 前端业务变化太快,经过半年的迭代之后,可能第一版的方案就反应不出现有代码逻辑了;

    • 前端的业务流程、交互流程比后端复杂太多,而且可复用性差,需要花费大量时间去思考和整理,而且对抽象能力有比较高的要求;

    • 前端开发效率高,不会有历史包袱,有时候直接重写的效率反而更高;

    • 后端上在语言和 IDE 对重构的支持远比前端好太多;

    • 后端比较成熟了,比如常见的 mvc 分层都几乎是约定了,前端要不要 model 层,要不要 service 层都是要讨论的,要不要 reduxredux 存什么数据,每个人的理解不一样的;

    • 前端人员的抽象思维和工程化能力总体还是比后端弱的;但是这些原因其实都不是我们不做方案设计的理由,方案设计是个结构化思维的过程,他不光是能让项目更好执行,也能提升开发者本身的架构能力和宏观意识。我们要把自己做的东西展示出来,不光展示给同行看,可能还要展示给其他岗位上的工作人员看,甚至展示给用户看。如果我们只是会写程序,不会在文档中恰当且优雅地描述自己的想法,那么就真正的成为“码农”了。

    所以,同学们在平时开发的时候多想一想如何做设计吧。

    展开全文
  • 如何写好项目规划和方案设计文档

    万次阅读 多人点赞 2018-07-27 09:49:14
    在工作中,很多时候,我们都需要就一个问题提出一个解决方案,这时候,我们很可能需要产出一个文档来供大家讨论,并指导下一步工作计划。 问题可大可小,形式上是否叫它为一个项目并不重要,重要的是为了解决这个...

     

    在工作中,很多时候,我们都需要就一个问题提出一个解决方案,这时候,我们很可能需要产出一个文档来供大家讨论,并指导下一步工作计划。

    问题可大可小,形式上是否叫它为一个项目并不重要,重要的是为了解决这个问题,项目规划和方案设计的流程是一致的。就大数据平台构建的语言环境来说,它可以是整个平台体系的搭建方案,也可以是具体某个组件如调度系统的建设,还可以是某个具体的功能点或问题改进比如用户任务脚本的依赖关系分析,系统稳定性的提升等等。

    一篇项目规划和设计文档的好坏,往往决定了一个项目整体的调性和可预期的产出结果。但是,这么重要的文档,真正能写好的同学却并不多,很多同学甚至可能都没有意识到它的重要性,而仅仅是把它当作领导要求的一个软件流程的规范来简单应付,怎么快怎么来。

    事实上,撰写项目规划和设计文档,最重要的不是文档的模版和格式,而是里面的具体内容,它往往需要结合实际客观环境因素来综合考虑,平衡取舍,是一个需要充分脑力活动的工作。尽管如此,在大多数情况下,还是有一些相对通用的指导原则可以帮助我们更好的完成这项工作。

    本文侧重于方案的需求分析到概要设计部分,因为这部分内容通常是最容易被大家忽视,也最需要方法论和“端正的思想”来指导的 ;)而详细设计相关内容,考验更多的是技术的深度,以及如何做到全面周到,我计划在后续文章中另行阐述。

    总体原则和目标:

    首先,需要有明确项目背景,目标,以及核心需求分析

    方案规划设计文档的好坏,几乎完全取决于这一部分内容。但多数同学在这一部分内容身上,往往花费的时间却是最少的,常见的方式,就是“直奔主题”,上来就写具体要做的事

    项目背景和目标

    项目背景不是让你写一堆无关痛痒的铺垫材料。实际上,项目背景的作用是:

    Why?为什么要在这个时候做这个项目?

    换句话说,就是这个项目从产品或业务的角度,最核心的推动力是什么?再换句话说,痛点是什么?

    有痛点自然就有目标,你希望项目最终以什么方式解决问题,能达成什么目标。

    背景和目标的阐述,必须要能够自然合理的推导出下一部分内容:项目的核心需求/功能是什么。

    如果项目背景,目标的描述不能起到这个作用,那这一节内容就没写好,因为项目方案文档就缺乏了根本的出发点,后续的内容都没有了好坏对错判断的基本依据。

    项目核心需求

    项目核心需求和项目目标有什么区别?实际上没有严格的区别,只是对需要解决的问题的概括抽象程度的不同,或者描述角度的不同。

    目标可以理解为希望达到的一个状态,是抽象的,和技术方案无关的偏结果角度的表述方式。

    而项目核心需求,可以理解为了解决背景描述的问题,为了实现那几个目标,进一步推导出来的,在当前系统环境或方案框架体系中:必须要提供的产品功能形态,或者是必须满足的关键特性,又或着是不能违背的约束条件。你也可以理解为用更技术的语言进行细化描述的项目目标。因为目标和背景的不同,可能同一件事推导出来的核心需求也不同。

    这么说比较抽象。举个例子,如果我想构建一个数据交换服务或ETL系统,那么上述各环节的内容可能是(简化的写):

    • 背景 : 当前数据ETL链路极端难用,效率低下,稳定性差,维护代价高,用户抱怨多等等。
    • 目标 : 用户全自助,简单易用;可维护性好;性能高;可靠性好。
    • 核心需求 :比如针对“用户全自助,简单易用”这点(其它目标可以类似分析推理),可能是:
      • 提供统一的,标准化的配置后台:用配置的形式表达ETL业务语意,屏蔽下层实现细节。
      • 提供完善的错误反馈信息/机制:让用户能自助解决使用中遇到的问题。
      • ETL业务流程标准化:将最佳实践沉淀下来,通过配置的方式让用户选择,减少重复工作,降低用户开发的难度,规避使用姿势错误可能造成的问题。

    讲完区别,继续回来讲,这部分内容的要求。很多同学在写这部分方案的时候,很容易把需求和实现手段混为一谈。所以:

    核心需求的重点是:本质上需要提供什么能力,而不是具体实现上要做什么

    换个角度说,核心需求的描述方式是:要做成什么样,是功能目标而不是实现手段。

    在完整的项目文档中,显然目标和手段都需要,但是

    目标必须先于手段,而非相反

    原因也很简单,脱离了目标谈手段是没有意义的,很容易导致方向做偏,使得最终的结果产出背离了项目最初真正的需求出发点。

    实践中,做成什么样和怎么做有时候很难绝对分开。一句话的描述方式可能既包含了目标需求也包含了实现手段。那么,怎么判断这部分内容写得是否满足要求呢。

    • 如果你描述的侧重点只是需求的一种实现方式,而这个需求可能还有更多的其它实现方式,或者即使真的只有一种实现方式,你所描述的内容的也只是因果关系中,间接的因而非直接的果,那么很可能你描述的就只是手段而非目标。
    • 如果看文档的同学看完只知道你要做什么,而不知道做这些是为了什么?是否做这些就足够了,还应该做点别的?是否有别的解决方案,又或者做完了到底有什么用。那么也很可能是因为你把需求和实现手段混为一谈了。
    • 核心需求必须是本质的,一定要实现的功能,它是一个原则,不是工作列表。不要事无巨细,凡是想做的都列在上面,那样反而淡化了项目最根本的诉求。但它也必须足够全面,要能确实解决项目目标中所提出的要求,应该用适当抽象的语言概括一个完整的事项。

    总结一下,核心需求的根本目标是,让参与项目的同学有方向感,能够知道这个项目最终想要通过提供哪些能力,满足哪些约束条件来解决问题,至于怎么实现,具体要做哪些事,那是下一步才需要回答的问题,简单来说:先选择做正确的事,再考虑怎么把事做正确。

    其次,需要对现状和问题进行充分的收集和分析

    这一部分内容,从实际操作的先后顺序来说,未必是第二步,很可能在我们总结前面的背景,目标,核心区需求的时候,就需要加以收集和分析。

    不过,从方案文档的角度来说,放在这里,是为了进一步细化问题,分析目标,核心需求与当前现状的差距在哪里,具体有哪些实际问题需要解决。为后续具体的实现方案,准备必要的输入信息,确定工作的优先级,重要性,项目迭代的步骤等等。

    需要强调的是,现状和问题分析,要围绕前面的核心需求的条目展开,两者是强关联的,不要相互脱节,各讲各的

    这块内容本身没有太特别的地方,就是现在实际情况如何,有什么问题,关键是如何把问题收集完整。

    所以这部分内容,难的是如何发现问题,很多做技术的同学往往容易陷入只关心技术难点,只能看到技术问题的局面中,而实际上,更多的问题往往是整体流程如何设计更加合理的问题,而不是技术方案绝对对错的问题。

    尽管行文上不难,但它的重要性,也往往容易被忽略,很多情况下被简单对待。实际的情况是,很多项目的方案计划往往是在对现状问题相关信息没有充分收集和分析的基础上就做出来的。导致项目方案后期不断调整,或者一期一期的总是在小步迭代,甚至不断推翻重来。而最终使用方真正关心的问题却一直没有得到重视和解决。

    最后,是输出解决方案

    定完需求目标,分析完问题和现状,接下来才是规划具体做什么,怎么做,什么时候做。

    这部分内容,强依托前面的核心需求和问题分析工作,没有做好前面的准备工作,千万不要着急开始动手“规划”方案!!!

    那么具体写的时候有哪些注意事项呢?

    做什么:

    • 做什么和前面项目目标的要求刚好皆然相反,需要输出明确的可执行的事项,而不是模糊的不可执行的要求。
    • 具体做的每一件事情,都要和前面的核心需求和现状问题对应上。如果你发现有些工作,和前面的目标没有任何关联性,那么考虑一下目标是否需要再评估调整,或者这件事情根本就是不重要的。
    • 要做的事项列表,是一个经过归纳思考以后的总结,而不只是一个个零散的事情的随机列表。需要有重点和优先级。如果有必要,以归类,分组等形式结构化的组织相关联的事项。
    • 完整的事项列表,应该是一个和最终目标对应的完整解决方案,而不仅仅只是完成目标工作中的某一个环节。
      • 比如面向用户的终端产品项目,需要包括整个产品的交互逻辑,业务流程的规范设计等等,而不仅仅是对底层系统实现和后台功能点的设计。
      • 这点很多同学也很容易忽略,总觉得功能和架构的实现才是有挑战,需要规划的内容,而产品的形态并没有花心思去琢磨,事后开发前端时才来考虑。实际上后者可能才是真正影响项目成功的关键,也很可能会影响到底层架构的设计和取舍。类比一下,好比一个用户产品都开发完了,才来考虑埋点,数据采集和数据分析的工作,这时候就很被动了。

    怎么做:

    • 前期方案文档,没有必要列出详细的技术方案细节,只需要一个整体的技术方向选型和初步的架构设想。但是,如果是涉及到核心需求能否有效满足的关键的技术点,有可能影响整体的架构或产品实现的,那就有必要就可能的方案的进行详细的评估并得出初步的结论。
    • 无关架构或进度安排的方案细节,没有必要写太多,可以后续再补充。
    • 方案中有不明确的地方,即使没有时间调研,也不要简单的略过不写,要在文档中明确的把问题写出来,给出下一步调研的方向计划等。归根到底,方案文档中,对每一个已知重要的问题,都需要一个明确的结论或者可以后续跟进的计划,以免事后遗漏。

    再强调一下,做什么和怎么做就是手段,既然是手段,就要写得足够具体,具体到有明确的可落地实施的事情,有明确可以衡量的标准,或者针对当前存在的一个具体问题,不要在这个地方又写得像目标,没有明确的可执行的点。

    继续举上文数据交换服务的例子,针对其中的一个核心需求:

    • ETL业务流程标准化:将最佳实践沉淀下来,通过配置的方式让用户选择,减少重复工作,降低用户开发的难度,规避使用姿势错误可能造成的问题。

    这个内容要写具体的要做的事项。以下方式来写可能就是不合格的,因为不够具体,还没有足够思考:

    • 总结最佳实践
    • 生成标准的流程
    • 总结常见的错误

    以下内容可能就更加明确,更加可落地一些:

    • 统一当前增量数据导入的存储,合并,归档方案
    • 将常见合并,去重逻辑标准化,通过配置自动生成任务脚本
    • 制定ODS快照表生命周期管理方案,规范存储路径和命名方式,定期清理过期数据。

    什么时候做,谁来做:

    • 这是做什么和怎么做的进一步延伸,需要强调的是整个项目如何实施的整体步骤计划,而不仅仅是简单的列一下每项工作的人员和排期,
    • 需要分析系统可能的迭代步骤(包括可能的短期应急和长期解决方案),上下游依赖梳理,需要协同进行的工作,最终项目上线时可能的业务迁移,数据迁移,系统集成等等外围工作的安排。

    如果不是工期严格要求,deadline为导向的项目,整体的依赖和步骤往往才是在项目规划阶段需要重点阐述的内容,也是有可能对整体产品的进度,风险产生影响的事项

    而具体工作工期的安排,说实话,多数情况下,反到没有那么重要。如果整体工作和步调没考虑周全,工期排得再科学,再精细,也毫无意义。

    总结一下,什么时候做什么事,最重要的目的,不在于工期的计算,甚至也不是人力资源的安排,而是为了理顺事情依赖关系,控制可能的意外风险,提升项目开发进度的可控性。

    小结

    方案规划设计文档,绝对不是为了满足流程需要凑数的文档,也不是头脑风暴式的简单记录。它的根本目标,抽象来说是:明确问题,圈定范围,确定重点,阐明路径。本质是为了统一认识,控制风险。它应该是一个问题经过思考以后的输出的答案,而不是问题的调查报告,笔记或备忘录。

    它很像一个议论文体裁,事实,分析,结论缺一不可。所以,无论你的方案文档写的多么翔实,如果只是相关内容细节的罗列,只议不论,缺乏抽象总结,还需要阅读文档的同学再去揣摩项目意图,或者看完以后对项目所要做的工作为什么要做,重不重要,要做成什么样都不明确的话。那它就只是一个不合格的半成品,不能对后续的项目开发工作发挥实质的指导和规划作用。

    结论列表

    上面花了大量篇幅展开讨论,目的是说服你接受我的看法。

    如果你只需要明确的结论,那么再总结一下:

    总体原则:

    • 项目方案规划文档的根本目标是统一认识:明确问题,确定重点,阐明路径,控制风险。
    • 文档的撰写方式,是目标和需求先行,围绕出发点,逐步递进展开。
    • 文档的基本要素:背景,目标,核心需求,现状问题分析,关键方案难点解析,总体实施路径,工作事项列表,进度计划安排。

    再细化到一些注意事项:

    • 核心需求,必须是核心的,一定要实现的内容!不能缺,也不能滥。
    • 问题现状,工作事项,必须呼应核心需求,要有明确的相关性,不要无的放矢。
    • 围绕最终目标,输出完整的端到端的解决方案,而不是局部环节的方案。需要从最终产品/功能形态的角度考虑要做的事,而不是仅仅考虑底层技术实现。
    • 事项目标列表,不要仅仅罗列要做什么事,更重要的是说明想要得到的结果,而不仅仅是描述实现手段。
    • 所有工作事项,需要明确思考过实施步骤,重要性和优先级,结合目标和需求,进行抽象归纳,而非简单随机罗列。
    • 要有明确的计划排期,但更重要的是,要完整的分析思考可能的上下游和周边工作依赖。排期只是结果,完整的梳理才是关键。

    两条辅助判断依据:

    • 如果开发同学看完文档,无法根据后续开发过程中遇到的实际情况,调整工作事项和优先级,完善和改进这个文档,那么大概率这个项目方案文档是没有写好的。因为这个文档可能只起到了事项罗列和工作安排的作用,却没有起到指导思考,授人予渔的作用
    • 如果看完文档,这个项目的最终产出你无法预见,你对项目的目标最终能否实现无从判断,那么这个项目方案文档大概率也是没有写好的。因为这个文档自身的归纳总结可能还没做到位,风险和问题可能还没有评估清楚,还需要走一步看一步。

    提示

    写项目方案文档,不是八股文,所以本文的内容并非绝对的教条,你当然可以根据项目的实际情况和复杂程度自行调整,但前提是你真的知道你为什么要这么做,而不仅仅是为了偷懒

    本文多数内容是各种观点,注意事项,结论和目标,具体如何做到这些,每个同学都可以自行思考。当然除了思想和目标端正,每个环节,其实也有一些具体Tips和checklist可供参考。下一次再说,下一次再说吧。。。

    软广

    本文写的各项原则,在我们之前的项目实践上实际都有体现,有兴趣结合实例比对参考的同学,我再厚脸皮再推一下这本书 《大数据平台基础架构指南》

    京东,淘宝,中亚有售,JD购买链接 : https://item.jd.com/29923944547.html ;)


    常按扫描下面的二维码,关注“大数据务虚杂谈”,务虚,我是认真的 ;)

    展开全文
  • 如何找到最新的RFC文档

    万次阅读 2016-08-30 17:02:51
    分享一下我是如何找到对应最新的RFC文档,这其实还是蛮重要的,毕竟有的时候RFC前后的差异还是有的。 查看RFC最权威的网站是http://www.iana.org/,在IANA的protocols子页面下面有这样一个链接,如图1所示: ...

      最近需要看一下熟知端口对应的协议。看了一下RFC1060,觉得这个文档有点老了,就尝试着找一个新版本的。分享一下我是如何找到对应最新的RFC文档,这其实还是蛮重要的,毕竟有的时候RFC前后的差异还是有的。

      查看RFC最权威的网站是http://www.iana.org/,在IANA的protocols子页面下面有这样一个链接,如图1所示:

     

    图1

      RFC Editor Queue这个网站里面列出了所有RFC文档,并按照状态进行了分类,如图2:

    图2

      有草案标准的RFC,有建议标准的RFC还有RFC状态发生改变的等等。我在RFC Status Changes子页面搜索RFC1060(该文档列出了网络通信中所用到的数字,包括常用端口以及协议号等等),如图3:

     

    图3

      可以看出该文档的最近修改日期是1992,发布时状态是UNKNOWN,目前状态是HISTORIC,也就是说该文档目前已经不用了。点进去看,如图4:

     

    图4

      里面说明了该文档作用替代了以前的RFC1060,但是该文档又被RFC1340所替代。同理,继续点击RFC1340,一级一级的定位,最终我得出相关最新为RFC3232,其内容如图5:

     

     

    图5

      可以看出在RFC3232中给出了最新介绍相关数字的变成了一个在线数据库,到IANA的官网PROTOCOLS子目录下面搜索numbers,最终找到最新的RFC6335,如图6:

     

    图6

      在这里面最终找到了最新的端口等数字信息,对比RFC1060其变化还是很大的,有些端口对应的协议时发生了变化。至于问什么不直接在图6的界面搜索是因为该界面的RFC不是很全面。为了找到RFC6335,还是挺不容易的。当然从前面的步骤让我了解到了RFC文档是不断被最新RFC替换和修订的。

    当然我们也可以直接从www.rfc-editor.org进入所有的RFC目录,搜索著名的RFC2616,如图7:

     

    图7

      可以看到RFC文档已经被RFC7230,RFC7231等文档所替代,所以我们在学习的时候是可以看看比较新的文档的,但是由于其目前状态还是DRAFT STANDARD,因此还是可以参考的,但我个人认为最新的比较好,因为修订的文档在一些知识点是会发生变化的。我也觉得是时候计划更新一下自己陈旧的知识了。

      可以看到RFC2616的最近更新时间是1999,而RFC7230是2014年,如图8:

     

     

    图8

      网络技术是在不断的发展和更新的,在确认类似一些数字所代表含义的时候,例如上述的RFC1060相关的,最好能够找到最新的版本。

    展开全文
  • LiveGBS设计文档 一、介绍 28181协议全称为GB/T28181《安全防范视频监控联网系统信息传输、交换、控制技术要求》,是由公安部科技信息化局提出,由全国安全防范报警系统标准化技术委员会(SAC/TC100)归口,公安部一所...
  • 如何撰写《软件项目方案文档

    万次阅读 2011-10-25 09:56:00
    1. 概述 1.1 必要性分析 分析开发该软件的必要性。 ...分析国内外同类型软件的种类,特定等,对国内外的情况进行分析和对比,并写出该类型软件和该领域技术的发展趋势。...点此下载《方案文档》模板。
  • 需求文档 | 产品需求文档(PRD)

    千次阅读 多人点赞 2018-08-07 16:52:56
    首先,大家先分享一句话:把需求文档当成一个“互联网产品”去管理,理解它的用户,关注它的体验,不停迭代,使其价值最大化。(引用) 既然把它视为一个互联网产品,那我们需要思考PRD的用户是谁,他们通过PRD...
  • 默认情况下,Visual Studio会在“解决方案资源管理器”中自动跟踪当前编辑的文件,并让其在“解决方案资源管理器”中突出显示。当在文件编辑区域切换不同的文件时,“解决方案资源管理器”都会自动突出显示当前编辑...
  • 之前的一个项目中碰到的问题,使用场景是:用户会将一份PDF格式的协议上传到页面,我们需要将这份协议转换成多张图片(一页文档对应一张图片),转换完成之后,用户点击导出按钮,将转换完成的图片通过压缩文件的...
  • 需求分析及技术方案设计

    千次阅读 2018-07-17 12:17:40
    此外,你自己还得根据产品经理编写的需求文档,可能还会自己设计一些产品原型图出来,让你看,去看,去研究; 第三个步骤,可能还需要作为一个项目的技术leader,去跟你的项目组内的成员,去讲解和讨论需求,要确保...
  • 问题背景: 在写学位论文时,或是其他各种Word文档,经常被列表编号的混乱排序整的非常无语,尤其是一级标题二级等次标题编号格式不同时。于是终于下定决心给自己好好整个模板。 问题描述:学位论文一般要求章...
  • MongoDB2.1、安装启动2.1.1、下载安装2.1.2、后台启动2.1.3、查看是否启动2.1.4、如果开了外网端口,用浏览器查看是否外网访问2.2、常用命令2.2.1、连接mongo2.2.2、显示数据库列表2.2.3、显示表单(集合)列表2.2.4...
  • Mockito PowerMock 版本对应关系

    千次阅读 2020-05-14 22:46:44
    mockitopowermock 版本对应关系 java.lang.ClassNotFoundException: org.mockito.exceptions.Reporter powermock-api-mockito powermock-api-mockito2
  • Office文档在线预览

    千次阅读 2019-04-12 22:15:09
    测试方案二:使用第三方服务方案三:使用微软 Office Online 服务永中文档预览服务详解1. 试一试在线预览!2. Web调用3. Java调用 方案一:word转html 使用Apache POI将word转为html,生成静态html,预览功能直接...
  • SpringBoot 如何生成接口文档,老鸟们都这么玩的!

    千次阅读 多人点赞 2021-08-26 15:27:58
    那今天我们就带来老鸟系列的第三篇:集成Swagger接口文档以及Swagger的高级功能。 文章涉及到的代码已经上传到了github,希望最终能应用在你们实际项目上,当然如果有其他需要我添加到内容也可以直接留言告诉我,我...
  • 前言:腾讯位置服务为各类应用厂商和开发者提供领先的LBS服务和解决方案;有针对Web应用的JavaScript API, 适合手机端Native APP的各种SDK, WebService接口,适合小程序的插件和各类地图API等。 目录 接入指南 ...
  • 新手学Python之学会查阅API文档

    万次阅读 多人点赞 2021-03-08 15:53:33
    时至今日,当有新手在群里提问时,也不时会看到下图的解决方案,即通过百度或者其他搜索引擎来解决问题:   诚然,很多问题可以通过搜索引擎得到答案。但往往忽视了解决Bug的第一种方法:查阅API文档。对于新手来...
  • 如何写好一篇技术型文档

    万次阅读 多人点赞 2022-01-26 13:14:32
    如何写好一篇技术型文档 周智 2022/1/20 参加工作时间久一点的工程师应该有这样一个体会:自己平时代码写得再多再好,可一旦要用文档去描述或者表达某一个事情或者问题时,都感觉非常困难,无从下手,不知道自己该...
  • ES系列之嵌套文档和父子文档

    千次阅读 多人点赞 2020-03-26 19:45:47
    需求背景 很多时候mysql的表之间是一对多的关系,比如订单表和商品表。...索引是独立文档的集合体。不同的索引之间一般是没有关系的。 不过ES目前毕竟发展到7.x版本了, 已经有几种可选的方式能...
  • 撰写项目的解决方案要点解析

    万次阅读 多人点赞 2018-12-12 10:23:55
    一、解决方案难写在哪里? 很多人对写方案非常没有信心,一涉及到方案的事情,就束手无策,到处求人。 作为一个公认的方案打手,意思是写方案就象打字员一样,我觉得我在这方面确实是有绝活。 我基本上都是在方案...
  • 所以这里整理学习一下相关文档需要的内容。文章并不设计对所有需求分析,概要设计和详细设计的详细描述。因为这其中的任何一点都可以单独提取出来成为软件工程学科中的一本书籍内容。 1 软件设计的整体流程: 软件...
  • 前言:最近楼主遇到一个问题,就是在学校(楼主是普通本科计算机专业的学生)评优评奖的时候,需要在学校系统的网页上提交一个Word文档,而这个文档呢,学校的系统(金窗公司开发的校园管理信息系统)用的是NTKO的...
  • swagger接口文档出现的空文档问题

    千次阅读 2021-05-18 11:24:47
    和方法上面的@ApiOperation(value = "ExamPaper条件分页查询",notes = "分页条件查询ExamPaper方法详情" ,**tags = {"ExamPaperController"}**)value tags 对应不一致问题 解决方案方案1.将@
  • 学习了关于文档的上传,下载,以及属性标签的应用,朋友们估计也会想到,前面学习到了关于列表的数据权限配置, sharepoint 2016 学习系列篇(15)-自定义列表应用篇-(4)数据权限配置 那么,文档库的文档,是否也有...
  • 软件开发生命周期及各阶段文档

    千次阅读 2021-04-05 20:12:07
    软件开发生命周期及各阶段文档 本文主要有两方面内容: 软件开发生命周期各阶段 软件开发生命周期各阶段所涉及的文档 软件开发生命周期 软件开发生命周期定义: 软件从定义到消亡所经历的过程。 软件开发生命周期...
  • 软件开发文档模板

    万次阅读 多人点赞 2018-08-13 15:55:49
    在需求或设计发生变更时,需要对原有文档进行修改,并提供完整的变更记录, 以使变更处于可控制的状态。变更单如下表所示: 表  2-1  变更单 需求变更申请 申请变更的需求文档 ...
  • 一份完整测试方案模板

    万次阅读 多人点赞 2020-04-19 10:55:37
    一份完整测试方案模板 文章目录前言整体架构图1.1 编写目的1.2 项目背景1.3 测试目标1.4 测试参考文档1.5 测试提交文档1.6 术语和缩写语2.1 测试配置要求2.2 测试方法2.3 测试数据2.4 测试策略2.4.1 单元测试2.4.2 ...
  • 后端开发之如何写接口设计文档

    千次阅读 2021-04-15 15:07:55
    那么在现实生活中的这些接口其实就是一种契约,连接两个物件,只要你按照接口的要求来做,就能和另外一个按照这个接口对应的物件相互连接。比如所有三头的插头都可以插入三个眼的插板,充电器也一样。 接口规范是...
  • 需求文档是典型的说明文,力求逻辑清楚、言简意赅。对语序、用词要求严格。宁可枯燥也不能模棱两可,这就暗示需求文档有它的语法。 本文继“后端产品经理笔记:数据传输和写入”之后,梳理了需求文档的语法,有...
  • 【软件工程】写文档真的很重要——文档总结

    千次阅读 热门讨论 2014-08-02 11:44:57
     2、管理文档:这类文档在软件项目开发过程中,由软件开发人员制定的需提交管理部门的一些工作计划、工作方案和工作报告。通过阅读这些文档,管理人员能够了解软件项目开发活动安排、进度、资源使用等情况。  3...

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 300,666
精华内容 120,266
关键字:

如何使方案的列表与文档对应

友情链接: Nice_Ass.rar