管理感悟：技术文档有用吗
管理感悟：技术文档有用吗
柳鲲鹏
2007-8-7
关键字：技术文档 作用
简介：虽然大家都认为技术文档应该有用，但事实告诉我们技术文档是没用的。别把写技术文档当作工作，浪费时间精力，有这种时间，不如要求员工多写一点注释，或者想办法训练一下员工。
在软件公司，最想做的，也是最受指责的，而且是从上到下异口同声的问题，说是技术文档缺乏，应该是没有疑问的。但大家看到的现象，是抱怨的本人也常常以工作忙为理由拒绝做出至少自己不抱怨的技术文档。更加奇怪的是，公司照常运行，产品照常出，工作照样交接。看到这种矛盾的现象，我们不禁要问：技术文档有用吗？
技术文档，简单的说，就是指跟代码相关的技术说明。技术文档的目的是什么？首先技术文档不是为作者自己看的，主要是为工作接手人看的。文档本身有什么情况？
文档写得详细，这种结果常常是比代码还长。这种结果有意义吗？
文档写得简要。这种文档马上就被人批评为太简单了没有意义。
文档有问题。一个是内容跟代码不一致，另外一个原因是没有及时更新。这种情况下，可以说有不如无。
那工作接手人会看文档吗？如果接手人负责维护。大多数情况也就是解决几个BUG。此时通过DEBUG一路下来就差不多了（如果不幸是连DEBUG也不会的人那是公司的问题），搞不清楚原因加个特殊处理语句也解决。这种情况下文档自然无用。如果原有工作问题太多，要重新开发呢？这跟接手人能力相关：
接手人能力出色。这时他根本不会花时间研究文档浪费时间，而是直接动手从头再来。只有碰到个别极特殊的问题，他才可能参考一下老代码，这更用不上文档了。
接手人能力不出色。那么所谓重新开发就变成了搬代码。勤快的人还会趁机看一下代码把自己觉得不顺眼的地方改改（如果不幸改出错误就会老实了），有的干脆拷贝了事。这个时候，文档的作用又在哪里？
尽管大家都认为技术文档有用，但在所有事实面前，技术文档是的确没有起到你想象中的作用。有人会说写文档有助于理清思路，难道写代码时会有人故意思路不清楚吗？花大量时间做这种无用功，实在没有意义。有这种时间，不如要求员工多写一点注释，或者想办法训练一下员工。
如果非要写一点文档，我建议软件公司别赶什么时髦，一个简要的流程图足矣，加上一些必要的说明；如果觉得不够，还可以把一些主要的DEBUG调用路径写一下来加上说明，让人一目了然。总之别把写技术文档当作工作，浪费时间精力，对工作不仅没有帮助，反而引起误解。
管理感悟：技术文档有用吗相关推荐
- 市面售价2W的仿抖音短视频原生双端APP源码，带技术文档管理后台和数据库
这个短视频系统源码是2w某站购买来的仿抖音视频app,原生双端开发,带技术文档管理后台和数据库.非常适合用来做类似项目的基础开发框架,能节省大量的开发时间和试错成本. 除了直播没有开通,其他功能都是精 ...
- 使用Docker搭建RAP2(技术文档管理私服)
文章目录 前言 准备工作 安装 mariadb及redis安装 rap2-delos安装 rap2-dolores 安装 nginx配置ssl正式及解决跨域问题 安装确认 使用说明 前言 技术团队,文 ...
- 敏捷开发的技术文档管理
许多团队或个人都有一个观念是敏捷开发应该弱化技术文档管理,以达到敏捷的目的.其实不然,敏捷开发只是把开发的生命周期变成不断迭代的软件开发过程,在迭代的过程中应该包含了技术文档的整理完善,使其可以为下一 ...
- Guns 技术文档 v1.0
Guns 技术文档 v1.0 Guns 技术文档 v1.0 1. 序言 1.1 文档简介 1.2 Guns教程 1.3 获取帮助 2. 使用手册 2.1 下载项目 2.2 导入项目 2.2.1 ecl ...
- wms策略文档_内容策略：技术文档的新理念
wms策略文档 我们是否可以首先同意文档很重要,而我们想要更好的文档呢? 好. 这样一来,我就不必为为什么要关心而写三段式的报告了,这样您就可以保留更多的时间来阅读它会花费您的时间. 为了生意! 作为 ...
- Debezium系列之：使用Debezium接入PostgreSQL数据库数据到Kafka集群的详细技术文档
Debezium系列之:使用Debezium接入PostgreSQL数据库数据到Kafka集群的详细技术文档 一.概述 二.连接器的工作原理 1.安全 2.快照 3.Ad hoc snapshots ...
- 智慧社区综合管理平台——需求文档（第九组）
目录 1.引言 1.1 项目简介 1.2 目的 1.3 文档的范围 1.4 预期的读者和阅读建议 1.5 产品的范围 1.6 参考文献 2.总体描述 2.1 产品视角 2.2 用户特征 2.3 系统 ...
- Debezium系列之：使用Debezium接入SQL Server数据库数据到Kafka集群的详细技术文档
Debezium系列之:使用Debezium接入SQL Server数据库数据到Kafka集群的详细技术文档 一.Debezium概述 二.SQL Server 连接器的工作原理 1.Snapshot ...
- unity3d 脚本参考-技术文档
unity3d 脚本参考-技术文档 核心提示:一.脚本概览这是一个关于Unity内部脚本如何工作的简单概览.Unity内部的脚本,是通过附加自定义脚本对象到游戏物体组成的.在脚本对象内部不同志的函数被 ...
- Guns 技术文档 v5.1
@stylefeng 2018-10-17 10:22 字数 27433 阅读 4795 Guns 技术文档 v5.1 stylefeng技术文档 Guns 技术文档 v5.1 1. 序言 1.1 文 ...
最新文章
- python扫描端口脚本_Python实现的端口扫描功能示例
- Xshell连接Ubuntu报错 “服务器发送了一个意外的数据包”
- Tcode SCU3查看table log的error message - 如何查找necessary PFCG role
- 部署SAP UI5应用到ABAP服务器时，Webcontent path的determine逻辑
- 判断对象oStringObject是否为String
- python乘法运算为什么是重复_警惕python中的*重复符（运算符）
- c语言ntc程序,NTC热敏电阻测温度 单片机C和汇编源程序
- Xshell连接Linux
- qt判断读入的字符串是否含有英文_重复的子字符串
- knife4j--api请求参数不一致问题
- 数据仓库与数据挖掘课后思考题整理
- 火电厂（ 4×300MW ）电气主系统方案与设备配置初步设计
- 自动交易软件的功能特点能满足哪些要求？
- adb无线连接Android手机
- Typora + PicGo + Github实现图床
- Android 源码之Recovery升级的过程和问题分析
- Cadence OrCAD Capture 修改添加阵列PIN的递增方向的方法
- 计算机无法关闭密码保护共享,xp系统怎么关闭密码保护共享
- unity退出，从新开始，暂停
- Laravel OAuth2 (二) ---配置与数据库设计