如何写技术文档

如何写技术文档"/>

如何写技术文档

在浏览CouchDb.com网站的时候，我偶然看到了Damien Katz写的关于技术文档写作过程的描述，觉得非常滑稽。大家知道，现实情况是这样的：

欢迎来到技术文档的世界！

你的处境跟其他的文档工程师没啥不一样。技术文档的写作过程如下：

1. 询问程序员那鬼东西是怎么工作的。
2. 沉默一片……大家都聋了吗？
3. 听见蛐蛐在叫……
4. 听见风吹草动的声音……
5. 不管啦，开始写点东西出来。任何东西都行。
6. 把写出来的东西给程序员看。
7. 在一边看着：程序员发现你写的东西完全不得要领，很抓狂。
8. 在程序员斥责你的时候，他也会抛给你一些有价值的技术信息。
9. 收集这些“珍品”，因为这些是你能得到的唯一可靠的技术信息。
10. 拼命把这些信息组织在一起，使它们具有可读性，并且在技术上也是准确的。
11. 跳回到第6步。

好吧，你不是做文档工程师的料。没关系，我也不行。不过，人们已经在努力把这件事做得更好。我也会继续努力的。

在我的职业生涯里，上述两种角色我都曾扮演过。这事挺有趣的，因为它是真的。我还记得，我在Mike Pope的博客上看到过极其相似的描述。