专栏首页落影的专栏关于文档的那些事

关于文档的那些事

前言

如何写这篇分享,本身就是一次分享。

正文

为什么要些写文档?

1、让初次接手业务的同学有一个大概了解; 2、作为自己的备忘录,减轻记忆的负担,也方便后续快速跟进; 3、先从宏观角度来思考完备性,实现过程中可以作为指引; 4、方便其他同学来提出建议,共建和谐社会; 5、和团队其他角色沟通用时,脑海关于需求的千丝万缕先用文字、图表描述出来,在沟通过程中就可以精确的描述和表达,再具体讨论有疑问的点,最后勾勒出整个需求的蓝图; ...

在工作过程中遇到很多问题,解决这些问题的过程中会积累经验和见识,写文档就是把这些知识进行抽象、整理,继而沉淀下来。当我们再次遇到类似的问题,我们就能快速在脑海、文档中检索出来对应的解决方案。

要写什么文档?

信息是数据的组合排列,比如微博上每日最新的资讯,朋友圈不断更新的动态。 知识是大脑对信息的组合与整理,对别人而言的知识,对自己可能只是信息。 信息经过大脑的整合,组织出自己能够理解的知识并沉淀下来,则成为个人的知识、团队的文档。

写文档的几个思路: 太简单的不写; ==> 浪费时间; 自己不熟悉的不写; ==> 误人误己; 炫耀性的文章不写; ==> 蹉跎岁月; 没有总结的不写; ==> 先思考后产出; 看完没有收获的不写; ==> 没有价值;

按照这个思路,我常写的文档以下几种: 1、方案设计文档——方案评审用; 2、经验总结文档——抽象避免重复采坑; 3、问题处理文档——专项问题跟进; 4、知识提炼文档——深入学习;

这些文档里面有分享价值的内容,我都会脱敏后发布出来,这样也是日常更新的主要来源。 写文档的目标是掌握知识,并不是简单的信息积累,更多是组合、整理、思考、启发。

怎么写文档?

1、明确此篇文档的目标人群; 以技术方案评审文档为例,文档的目标人群是参与评审的技术同学,所以描述需要更加抽象,避免出现大量的细节; 以反馈问题跟进文档为例,文档的目标人群是运营、产品、开发等,所以需要针对特定的逻辑,用通俗的语言去描述问题的前因后果,避免出现代码逻辑和无法理解的词汇;

2、理清要表述问题的中心; 技术方案评审文档,是为了阐述技术方案的整体设计; 反馈问题跟进文档,是为了针对某个问题给出结论;

3、梳理整个描述逻辑; 以技术方案评审文档为例,大致流程可以是 介绍背景=》问题思考=》抽象提炼=》思考总结; 以反馈问题跟进文档为例,可以是 问题表现》问题分析》出现原因》修复方案》后续问题》质量监控;

4、善于用图; 描述功能、逻辑的基本过程,用流程图; 描述实现过程中的模块关系,用模块结构图; 描述逻辑功能下的数据变化,用数据流图; 描述随着时间的状态变动,用时序图; ...

设计的时候要有分层的思想,比如说分UI层和数据层。在思考整个功能的时候,可以把客户端通过接口请求到的数据当成物料。把数据展示出来,用户会进行操作,有可能会影响数据本身。把原始物料和生成的数据通过埋点等通知后台,就是一个反馈的过程。 粗细有度,方案评审尽可能屏蔽实现细节,经验总结则要仔细回顾遇到的问题。 模块化的思想同样很重要,用模块来抽象分析需求,可以更好屏蔽实现细节,整理出模块间的依赖,再用接口(方法)等来描述模块间相互的调用,这样也有助于功能的扩展分析和模块细化。

以某业务的视频播放为例,我们可以抽象出来哪些模块? a.底层播放器模块,处理底层的播放逻辑; b.封装播放器模块,对模块a的封装,根据业务需要调用模块a; c.具体业务逻辑模块,这里目前可以细化出业务视频模块A、业务视频模块B等; d.全局播放控制模块,处理多个c模块之间的内容传递、播放控制协调等; e.扩展的播放打断模块,处理闪屏、音频等等多业务逻辑的兼容;

接下来把模块间的处理进行抽象。 a模块只被b模块调用,大概有play/pause/stop等接口; b模块只被c模块调用,c模块会有较多交互细节,比如说滑动的时候触发自动播放、进入时候会自动播放、划出屏幕触发暂停等,为了更好区分场景可以区分为autoPlay(自动播放)、manualPlay(手动点击播放)、pause等接口; 同理,再梳理出来c、d、e等模块之间的关系,这样出来一个整体的设计,实现的过程就可以按图索骥。 如果出现异常场景,第一反应是回顾这个设计图,思考这种问题是否在自己当初的设计场景里面,如果是那么有没有考虑解决方案;如果设计没有考虑这种case,那么应该从哪些模块去解决,可能会造成哪些影响。通盘考虑完之后,重新改动设计,最后才是代码实现。 有哪些模块、模块之间的依赖和调用,后续如何新增和修改模块,都是方案设计和评审的关注重点。

总结

文档很难尽善尽美,问题是解决不完,而成长也是永无止境。 当我们养成写文档的习惯,我们就已经迈出了第一步。 只要保持写文档,我们就必须去思考、总结,自然可以从工作中学习到更多知识。

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 鹅厂的成长收获

    毕业之后在上海、成都、上海的城市中徘徊,每一次城市迁徙都带我许多的烦恼; 于是在2017年初时,我回到了深圳,选择加入当时对我来说是神秘的存在——腾讯。 至...

    落影
  • OpenGL ES实践教程(九)OpenGL与视频混合

    前言 前面的实践教程: OpenGL ES实践教程1-Demo01-AVPlayer OpenGL ES实践教程2-Demo02-摄像头采集数据和渲染 O...

    落影
  • 使用VideoToolbox硬编码H.264

    前言 H.264是目前很流行的编码层视频压缩格式,目前项目中的协议层有rtmp与http,但是视频的编码层都是使用的H.264。 在熟悉H.264的过程中,为...

    落影
  • “杀”一个程序员不需要用枪,改三次需求就可以了!

    在很多软件公司,特别是一些创业型的团队中,对于这样的情景可能大家都很熟悉:项目经理或者产品经理(产品狗)口头或者简单记录一下软件产品的大致要做的功能,直接就让研...

    Java后端技术
  • 为什么SAP Fiori活的如此精致

    时间追溯到1992年,SAP的创始人们发布了R3版本,这是一个经典的出现。这个版本的系统提供包括所有业务领域的业务处理流程的集成的解决方案。

    matinal
  • 前端模块化开发解决方案详解

    AMD(常用在浏览器端,异步的,如requirejs)(Asynchronous Module Definition)

    半指温柔乐
  • css单边投影与双侧投影

    早晨在前端交流群里,有个朋友问css实现单侧投影的办法,因为这个朋友前几天刚发过照片,晒他买的csssecrets,我问他你书买来还没看吗? 他说来不及翻书了...

    练小习
  • CSS基本知识(慕课网)

    听着music睡
  • 谈响应式web设计代码实现

    在研究响应式的时候,记录了一些感想,分享出来,抛砖引玉,希望可以和大家一起讨论。总结下来,响应式比之前想象的要复杂得多。 1. ie9以下(不包括ie9)采用i...

    RP道貌不岸然
  • JS自定义右键菜单—复制到粘贴板(jQuery和原生JS实现)

    从入门到进错门

扫码关注云+社区

领取腾讯云代金券