互联网公司的技术人，为何不写文档？

互联网公司，技术侧，写文档有没有必要？

有必要。

要写什么文档？

至少要写整体设计文档，详细设计文档。

为何不写？

多是没时间，多是不会写，多是不肯意写。

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

整体设计文档，详细设计文档，应该包含什么内容？

总设和详设都应该包含的部分：
（1） 需求：通常以产品的语言描述，这一块能够拷贝产品需求文档中的story list部分；
（2） 名词解释（可选）：非相关领域内的同窗须要看到文档须要提早了解的一些概念性质的东西；
（3） 设计目标：又分为功能目标和性能目标，功能目标通常是对产品需求的技术描述，性能目标是根据产品给出的数据对性能进行的评估。通常来讲，新服务必需要有性能目标一项，性能目标可能会影响设计方案。

除了都应该包含的部分，整体设计通常还包含：
（1） 系统架构：通常来讲会有个简单的架构图，并配以文字对架构进行简要说明；
（2） 模块简介：架构图中若是有不少模块，须要对各个模块的功能进行简要介绍；
（3） 设计与折衷：设计与折衷是整体设计中最重要的部分；
（4） 潜在风险（可选）；

输出整体设计的时候，不少方案仍是不肯定的，故整体设计重点在“方案折衷”，方案须要在设计评审会议上确认。

整体设计评审完毕以后，此时应该是全部方案都确认了，须要输出各模块的详细设计。

详细设计重点在“详细”，须要包含：
（1） 整体设计结论汇总（可选）：整体设计上达成一致的结论有个简要概述，说明详设是对这些结论的实现；
（2） 交互流程：简要的交互可用文字说明，复杂的交互建议使用流程图，交互图或其余图形进行说明；
（3） 数据库设计：这个是应该放在总设仍是详设呢？
（4） 接口细节：输入什么参数，输出什么参数，根据接口前端、后端、APP、QA就可以并行作编码实现了；
（5） 其余细节：例如公式等；

理论上输出了详细设计以后，不管谁拿到了这个详设文档，都是可以完成该项目的。

其余最佳实践？

1、 大图

（1） 大系统或复杂流程，其架构图或者流程图会很是大，常常比A4纸或word的一页大不少，此时不宜在word中直接贴图形，贴了也看不清，建议将图放在wiki上，文档中直接贴连接；
（2） 必定要保存viso或者其余图形的源文件，不然从此改动起来要重画，代价可想而知；

2、 设计与折衷

（1） 设计与折衷是总设中最重要的内容，总设评审中，主要就是讨论这些折衷的优劣；
（2） 评审事后，不但要邮件周知结论，还要在总设中进行更新，说明最终决定使用了哪一种方案，为何使用这种方案；根据本身的经验，接手别人的模块、项目，拿到代码和文档，设计方案对我来讲彻底是个谜！！！
（3） 有时候由于排期或者其余缘由，不必定采用了最优的设计方案，此时更应该在总设中记录决策的过程与缘由；
（4） 最后，设计折衷是一个很好的自我辩解的机会：由于项目进度，或者历史遗留问题，我不得不采起了一个这样的设计，不要再骂我了。

3、 性能目标

性能目标是新模块文档必不可少的一部分，不少项目对性能影响较大的话，也必须撰写性能目标，性能通常来讲可能包含如下部分：
（1） 日平均请求：通常来自产品人员的评估；
（2） 平均QPS：日平均请求 除以 4w秒得出，为何是4w秒呢，24小时化为86400秒，取用户活跃时间为白天算，除2得4w秒；
（3） 峰值QPS：通常能够以QPS的2~4倍计算；
画外音：详见《架构，如何进行容量设计？》。

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

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

相关推荐：

《回表查询？索引覆盖？| 1分钟系列》新出炉
《优化工具，迅猛定位低效SQL | 1分钟系列》
《数据库容许空值(null)是悲剧的开始 | 1分钟系列》
《两类很是隐蔽的全表扫描 | 1分钟系列》

大家公司写设计文档么？