互联网公司的技术人,为什么不写文档?

简介: 互联网公司,产品迭代快,可能很多公司没有“文档”一说。但其实,写好文档,对系统和项目未来的维护是非常有帮助的。

互联网公司,技术侧,写文档有没有必要?

有必要。

要写什么文档?

至少要写总体设计文档详细设计文档

为什么不写?

可能是没时间,可能是不会写,可能是不愿意写。

本文试图分享一些经验,解决“不会写”的问题。


总体设计文档,详细设计文档,应该包含什么内容?
总设和详设 都应该包含的部分:
(1) 需求 :一般以产品的语言描述,这一块可以拷贝产品需求文档中的story list部分;
(2) 名词解释 (可选):非相关领域内的同学需要看到文档需要提前了解的一些概念性质的东西;
(3) 设计目标 :又分为功能目标和性能目标,功能目标一般是对产品需求的技术描述,性能目标是根据产品给出的数据对性能进行的评估。一般来说,新服务必须要有性能目标一项,性能目标可能会影响设计方案。

除了都应该包含的部分, 总体设计 一般还包含:
(1) 系统架构 :一般来说会有个简单的架构图,并配以文字对架构进行简要说明;
(2) 模块简介 :架构图中如果有很多模块,需要对各个模块的功能进行简要介绍;
(3) 设计与折衷 :设计与折衷是总体设计中最重要的部分;
(4) 潜在风险 (可选);

输出总体设计的时候,很多方案还是不确定的,故总体设计重点在“方案折衷”,方案需要在设计评审会议上确认。

总体设计评审完毕之后,此时应该是所有方案都确认了 ,需要输出各模块的详细设计。

详细设计 重点在“详细”,需要包含:
(1) 总体设计结论汇总 (可选):总体设计上达成一致的结论有个简要概述,说明详设是对这些结论的实现;
(2) 交互流程 :简要的交互可用文字说明,复杂的交互建议使用流程图,交互图或其他图形进行说明;
(3) 数据库设计 :这个是应该放在总设还是详设呢?
(4) 接口细节 :输入什么参数,输出什么参数,根据接口前端、后端、APP、QA就能够并行做编码实现了;
(5) 其他细节 :例如公式等;

理论上输出了详细设计之后,无论谁拿到了这个详设文档,都是能够完成该项目的

其他最佳实践?


一、 大图

(1) 大系统或复杂流程,其架构图或者流程图会非常大,经常比A4纸或word的一页大很多,此时不宜在word中直接贴图形,贴了也看不清,建议将图放在wiki上,文档中直接贴链接;
(2) 一定要保存viso或者其他图形的源文件,否则今后改动起来要重画,代价可想而知;

二、 设计与折衷
(1) 设计与折衷是总设中最重要的内容,总设评审中,主要就是讨论这些折衷的优劣;
(2) 评审过后,不但要邮件周知结论,还要在总设中进行更新,说明最终决定使用了哪种方案,为什么使用这种方案;根据自己的经验,接手别人的模块、项目,拿到代码和文档,设计方案对我来说完全是个谜!!!
(3) 有时候因为排期或者其他原因,不一定采用了最优的设计方案,此时更应该在总设中记录决策的过程与原因;
(4) 最后,设计折衷是一个很好的自我辩解的机会: 因为项目进度,或者历史遗留问题,我不得不采取了一个这样的设计,不要再骂我了

三、 性能目标
性能目标是新模块文档必不可少的一部分,很多项目对性能影响较大的话,也必须撰写性能目标,性能一般来说可能包含以下部分:
(1) 日平均请求 :一般来自产品人员的评估;
(2) 平均QPS :日平均请求 除以 4w秒得出,为什么是4w秒呢,24小时化为86400秒,取用户活跃时间为白天算,除2得4w秒;
(3) 峰值QPS :一般可以以QPS的2~4倍计算;

互联网公司,产品迭代快,可能很多公司没有“文档”一说。但其实,写好文档,对系统和项目未来的维护是非常有帮助的。
画外音:文档清楚,开发阶段变化小;未来迭代成本小。

本文转自“架构师之路”公众号,58沈剑提供。

目录
相关文章
|
Java
解决Java- 错误: 找不到或无法加载主类 HelloWorld.java
针对初学者使用javac,java等命令编译class文件时出现的经典问题,提供解决思路和方法。
10219 98
解决Java- 错误: 找不到或无法加载主类 HelloWorld.java
|
Web App开发
在 HTML 中禁用 Chrome 浏览器的 Google 翻译功能
在 html 标签中添加 translate=“no” 属性,浏览器将不会翻译整个页面。
680 0
|
Web App开发 前端开发 数据库
推荐GitHub上开源的一款独立开发者出海技术栈和工具合集
推荐GitHub上开源的一款独立开发者出海技术栈和工具合集
555 0
|
分布式计算 JavaScript 前端开发
超级实用!详解Node.js中的lodash模块和async模块
超级实用!详解Node.js中的lodash模块和async模块
|
边缘计算 人工智能 算法
操作系统的心脏:深入理解任务调度的艺术
在现代计算的宏伟舞台上,操作系统扮演着至高无上的指挥家角色,而任务调度则是其手中那根神奇的指挥棒,它不仅掌控着每一个程序和进程的命运,还确保了整个系统的和谐与高效运行。本文将引领读者踏上一场探索之旅,从基本概念出发,逐步揭示轮转调度、优先级调度等核心策略的神秘面纱,探讨它们如何在不同场景下发挥关键作用。更重要的是,我们将展望下一代调度算法可能带来的创新与变革,以及人工智能如何为这一领域注入新的活力。通过深入浅出的讲解,我们期待每位读者都能从中汲取知识的养分,获得深刻的启发。
183 3
|
存储 人工智能 运维
2024年IDC行业的深度挖掘:机遇、挑战与未来展望
国际连锁超市借助云计算应对节日促销的海量数据挑战,展示了IDC行业的重要性。作为数字经济基石,IDC负责数据存储、处理和传输,受益于云计算、大数据和AI的发展。政策支持和市场机遇驱动IDC行业迅速扩张,但同时也面临能源效率、数据安全和环保的考验。未来趋势包括AI自动化、量子计算、边缘计算和绿色数据中心,强调数据安全、智能运维和可持续发展。超大规模数据中心和绿色技术将是行业重点,确保数据处理能力与环境保护并行不悖。
691 0
2024年IDC行业的深度挖掘:机遇、挑战与未来展望
|
Kubernetes Cloud Native 网络协议
一文搞懂“镜像“和“容器“
一文搞懂“镜像“和“容器“
1248 1
|
JavaScript
Nuxt3 实战 (四):安装 Nuxt UI 和配置 Typescript 类型检查
这篇文章介绍了在项目中安装和配置Nuxt UI以及TypeScript的步骤。作者在前言中提到考虑了AntDesignVue和Element-Plus,但最终选择了NuxtUI,因为它更适合年轻化的项目,并且与Nuxt兼容。安装Nuxt UI需要执行一系列命令,同时会自动安装一些相关模块。然后,可以在Nuxt应用中使用Nuxt UI的所有组件和可组合函数。此外,还介绍了如何添加图标库和配置TypeScript。
441 0
Nuxt3 实战 (四):安装 Nuxt UI 和配置 Typescript 类型检查
|
存储 前端开发 算法
常见的前端加密方式有哪些?运用场景有哪些?
【4月更文挑战第12天】前端加密技术包括对称加密(如AES、DES)、非对称加密(如RSA)和Hash算法(如MD5、SHA-1)。对称加密用于本地数据加密、HTTPS通信,非对称加密常用于用户登录认证,Hash算法适用于数据完整性校验和密码存储。应用场景包括用户登录认证、敏感数据传输、文件加密和支付安全。加密技术结合访问控制、安全审计等措施,能提升数据和用户信息安全。
1416 9
|
负载均衡 前端开发 Java
11-微服务技术栈(基础):Gateway服务网关
微服务中另一重要组件:网关 进行了实战性演练,网关作为分布式架构中的重要中间件,不仅承担着路由分发(重点关注Path规则配置),同时可根据自身负载均衡策略,对多个注册服务实例进行均衡调用。本节我们借助GateWay实现的网关只是技术实现的方案之一,后续大家可能会接触像:Zuul、Kong等,其实现细节或有差异,但整体目标是一致的。
7119 1