如何写一篇好的技术文档
最近在公司内部审查（Review）一篇详细设计文档时，对于文档作者所写的文档觉得很多地方需要改进。对于其中所存在的值得提高的地方，我想不是我们中国软件行业的个别问题，相反，存在一定的普遍性。以下我列出了几个值得提高的地方。
1）文档的格式上存在不一致性的问题。格式有时是这样，有时是那样。一篇好的文档我想不光是内容写得好，其格式是很重要的一部分。试想，如果我们拿到了一篇格式上写得乱七八糟的文档，这一第一印象会影响我们的阅读心情吗？好的文档应当是从头到尾保持格式的一致性，这不仅仅是一种美，更是专业性的一种表现。
2）写文档的作者不能很好的站在读者的角度去思考。要写出一篇好的支持文档，作者应当站在读者的角度上去写。这简单的一句话，要操作起来，将其做好，还真不是一件容易的事。在写文档时，如果不站在读者的角度去思考，很容易写出一篇“自己一看觉得清清楚楚，别人一看却糊里糊涂”的文档。
3）文档求长不求精。一说到写文档，我不知是否有人将“文档应当长”当作是文档的必要属性。对于这一点，我想正确的态度是：求精不求长。一篇好的文档，应当写得简练易懂。写文档的目的是什么？是为了让别人明白我们所要说明的问题，要说明问题，并不需要一定将其写得长。一篇精炼的文档也意味着效率，即读者花很少的时间就明白我们想要表达的问题是什么。当然，从作者的角度来看，要写一篇精炼的文档，那得花更多的时间去斟酌。
4）图太少。有图不是一篇好文档的必要条件，但在不少情况下，用一幅图能很好的表达我们的思想，不是有那么一句话吗“好图胜过千言万语”，适当的采用一些图，一方面能为文档增色，另一方面也能更好的向读者传达我们的意图。
好了，值得提高的点也提出来了，如何去做好呢？我想下面是我所能想到的一些方法，在此，将与上面的提高点一一对应进行阐述。
1）对于格式问题，找一篇自己觉得格式不错的文档进行模仿，并将其做成一个模板，每次写作时以这一模板为基础。
2）写完以后，假设自己是读者多次阅读自己的文档。这一点要做好还是很难的，因为，我们很难完全站在读者的角度去读自己写的文档，我们不知道自己所知的哪些东西是读者所不知的，即很难界定与读者知识不对称的分界点。为了提高这一点，我想我们写文档时，应当多问自己一些问题，比如，读者具有与我一样的知识和经验吗？如果没有，我应当写哪些以弥补这种信息的不对称性呢？我写的这篇文档是基于一定的假设吗？如果是，是否应当将这一假设在文档中交代清楚呢？我所写的内容是否都在支持文档的主题呢？是否存在正交问题（即答非所问的问题）？等等。
3）在文档写完后多问一问自己，这篇文档还能写得更简单吗？是否可以将一些文字省去并用一幅图取而代之以达到使其简练的目的呢？不防时刻对自己说，简单也是一种美！
4）学习（并精通）一些行业所需的图形语言和工具，并加以运用。比如，我们软件行业的UML就是很好的一种表达语言，且随着UML的发展，其表达能力更加的强大。目前，业内有很我UML的工具，找一个不错的就行了，比如Visual Paradigm的UML工具就不错，工具其实只是一种工具，关键是掌握UML。只有我们很好的掌握一种图形语言，我们才有可能随时加以运用，从而为我们的技术文档服务。当然，像Microsoft的Viso也是不错的绘图工具，这要看我们想表达的是什么，从而加以灵活运用各种工具。
至此就好了吗？不，还有很重要的一点是：我们需要在思想上做一些改变，这种改变是什么呢？那就是：写出一篇好的技术文档是一个专业软件工程师的必要素养！我们必须抛弃那种软件工程师只要能写出漂亮的代码就行了的思想，而是要将“写好每一篇技术文档是专业软件工程师的必要素养”这一句话深入到我们的骨髓当中去，只有这样，我们所写的技术文档才会越来越好、才会越来越专业。
本文出自 “至简李云” 博客，请务必保留此出处http://yunli.blog.51cto.com/831344/168352
如何写一篇好的技术文档相关推荐
- 如何写出好的产品帮助文档？
大多数程序员都不喜欢写文档,有写文档时间,还不如重构一遍代码.早前我也这么认为,究其原因,一则自己不喜欢也不擅长写文档,代码是给机器读的,只要语法和逻辑没问题,计算机就会听命执行,而文档是写给人看的, ...
- 这谁写的技术文档？我想锤死他...
点击上方"朱小厮的博客",选择"设为星标" 后台回复"书",获取 后台回复"k8s",可领取k8s资料 很多技术人自己非 ...
- 技术人如何写好技术文档？
点击"开发者技术前线",选择"星标" 让一部分开发者看到未来 参加工作时间久一点的工程师应该有这样一个体会:自己平时代码写得再多再好,可一旦要用文档去描述或者表 ...
- 怎么才能写好技术文档？这是我的全部经验
▲ 点击上方"分布式实验室"关注公众号 回复"1"抽取纸质技术书 参加工作时间久一点的工程师应该有这样一个体会:自己平时代码写得再多再好,可一旦要用文档去描述或 ...
- 如何写出优秀的技术文档？
大家好,我是小枣君. 鲜枣课堂自从2017年5月开始正式创立,迄今已有3年多的时间.这一期间,我们的内容一直都坚持以技术类科普文章为主,输出了大约400多篇原创.其中绝大部分,都是我写的. 我的想法比 ...
- 优秀程序猿写技术文档的正确姿势
一.背景 写文档是程序猿进阶的一个必要步骤之一. 文档写的清楚,思路就更加清晰,也会让同事高看你一眼,多梳理业务也有很大帮助. 产品经理对需求文档基本是驾轻就熟信手拈来,但是大多数程序猿写技术文档却显 ...
- 如何写好技术文档——来自Google十多年的文档经验
文章目录 文档的重要性 为什么大多数人都不喜欢写文档? 如何产出高质量文档 像管理代码一样管理文档 明确你的读者是谁 清晰的分类 参考文档 设计文档 引导类文档 概念性文档 Landing pages ...
- android技术文档怎么写,技术文档编写指南
技术文档编写指南 首先请阅读文案风格指南 ##学习产品使用方式 最重要的必备的条件就是: 一定要亲自使用这个产品,至少是一遍通顺的流程要走完,不要求每一个接口都一定使用过,但是一个完整的功能片段是使用 ...
- 如何写好技术文档 - 来自 Google 十多年的文档经验！
星标/置顶 公众号????,硬核文章第一时间送达! 本文大部分内容译自<Software Engineering at Google> 第10章节 Documentation.另外,该书电 ...
最新文章
- Mybatis用法小结
- colab长时间处于正在连接
- docker 根据标签删除镜像_10 个 Docker 镜像安全最佳实践
- Wannafly挑战赛22 D 整数序列 （线段树维护三角函数值）
- 容器精华问答 | 如何进行跨机器的Container做Link ？
- Julia : win下cmd和repl中执行.jl程序
- 机场VIP会员管理系统
- Chrome浏览器查看Axure原型图文件，提示Axure RP Extension for Chrome
- 微信小程序 好用的UI组件库推荐
- Linux评分脚本,linux必看脚本大全
- erp系统与mes集成：制造业信息化发展中必不可少的阶段
- 计算机硬件开关打开无线网络适配器,笔记本无线网卡怎么打开【方法介绍】
- find命令的基础用法以及按文件修改时间查找文件
- 微信公众号素材图片去哪找？
- Spring+SpringMVC+Jsp实现校园二手交易系统
- 汇总阿里云GPU云服务器常见问题解答FAQ
- Mysql5 实现交叉表查询
- Android GridView的使用
- 精密空调 | 多机房分散式智能监控管理
- mysql查询 多门课程的平均成绩_Mysql_多表查询练习