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

2023-11-30 14:38

本文主要是介绍互联网公司的技术人,为什么不写文档?,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

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

有必要。

要写什么文档?

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

为什么不写?

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

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

总体设计文档,详细设计文档,应该包含什么内容?
总设和详设都应该包含的部分:
(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倍计算;
画外音:详见《架构,如何进行容量设计?》。


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

架构师之路-分享可落地技术

相关推荐

《回表查询?索引覆盖?| 1分钟系列》新出炉

《优化工具,迅猛定位低效SQL | 1分钟系列》

《数据库允许空值(null)是悲剧的开始 | 1分钟系列》

《两类非常隐蔽的全表扫描 | 1分钟系列》

你们公司写设计文档么?

这篇关于互联网公司的技术人,为什么不写文档?的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/437409

相关文章

SpringBoot3实现Gzip压缩优化的技术指南

《SpringBoot3实现Gzip压缩优化的技术指南》随着Web应用的用户量和数据量增加,网络带宽和页面加载速度逐渐成为瓶颈,为了减少数据传输量,提高用户体验,我们可以使用Gzip压缩HTTP响应,... 目录1、简述2、配置2.1 添加依赖2.2 配置 Gzip 压缩3、服务端应用4、前端应用4.1 N

使用C#代码在PDF文档中添加、删除和替换图片

《使用C#代码在PDF文档中添加、删除和替换图片》在当今数字化文档处理场景中,动态操作PDF文档中的图像已成为企业级应用开发的核心需求之一,本文将介绍如何在.NET平台使用C#代码在PDF文档中添加、... 目录引言用C#添加图片到PDF文档用C#删除PDF文档中的图片用C#替换PDF文档中的图片引言在当

详解C#如何提取PDF文档中的图片

《详解C#如何提取PDF文档中的图片》提取图片可以将这些图像资源进行单独保存,方便后续在不同的项目中使用,下面我们就来看看如何使用C#通过代码从PDF文档中提取图片吧... 当 PDF 文件中包含有价值的图片,如艺术画作、设计素材、报告图表等,提取图片可以将这些图像资源进行单独保存,方便后续在不同的项目中使

Java利用JSONPath操作JSON数据的技术指南

《Java利用JSONPath操作JSON数据的技术指南》JSONPath是一种强大的工具,用于查询和操作JSON数据,类似于SQL的语法,它为处理复杂的JSON数据结构提供了简单且高效... 目录1、简述2、什么是 jsONPath?3、Java 示例3.1 基本查询3.2 过滤查询3.3 递归搜索3.4

Python中随机休眠技术原理与应用详解

《Python中随机休眠技术原理与应用详解》在编程中,让程序暂停执行特定时间是常见需求,当需要引入不确定性时,随机休眠就成为关键技巧,下面我们就来看看Python中随机休眠技术的具体实现与应用吧... 目录引言一、实现原理与基础方法1.1 核心函数解析1.2 基础实现模板1.3 整数版实现二、典型应用场景2

Python实现合并与拆分多个PDF文档中的指定页

《Python实现合并与拆分多个PDF文档中的指定页》这篇文章主要为大家详细介绍了如何使用Python实现将多个PDF文档中的指定页合并生成新的PDF以及拆分PDF,感兴趣的小伙伴可以参考一下... 安装所需要的库pip install PyPDF2 -i https://pypi.tuna.tsingh

Python批量调整Word文档中的字体、段落间距及格式

《Python批量调整Word文档中的字体、段落间距及格式》这篇文章主要为大家详细介绍了如何使用Python的docx库来批量处理Word文档,包括设置首行缩进、字体、字号、行间距、段落对齐方式等,需... 目录关键代码一级标题设置  正文设置完整代码运行结果最近关于批处理格式的问题我查了很多资料,但是都没

Python自动化Office文档处理全攻略

《Python自动化Office文档处理全攻略》在日常办公中,处理Word、Excel和PDF等Office文档是再常见不过的任务,手动操作这些文档不仅耗时耗力,还容易出错,幸运的是,Python提供... 目录一、自动化处理Word文档1. 安装python-docx库2. 读取Word文档内容3. 修改

使用Python快速实现链接转word文档

《使用Python快速实现链接转word文档》这篇文章主要为大家详细介绍了如何使用Python快速实现链接转word文档功能,文中的示例代码讲解详细,感兴趣的小伙伴可以跟随小编一起学习一下... 演示代码展示from newspaper import Articlefrom docx import

浅析如何使用Swagger生成带权限控制的API文档

《浅析如何使用Swagger生成带权限控制的API文档》当涉及到权限控制时,如何生成既安全又详细的API文档就成了一个关键问题,所以这篇文章小编就来和大家好好聊聊如何用Swagger来生成带有... 目录准备工作配置 Swagger权限控制给 API 加上权限注解查看文档注意事项在咱们的开发工作里,API