偶尔看到一篇有趣的文章,诙谐地描述了技术文档的写作过程。
我相信在实际工作中并非都是这样的,但这确实是有可能出现的情况:由于程序员太忙、不重视、认为 TW 应该具备和程序员一样的技术水平等各种原因,造成 TW 很难获取撰写技术文档所需要的信息。
这时候 TW 应该如何应对,相信大家各有各的方法。
曾经有人建议过一个方法: 在无法获得信息的情况下,先尽自己的努力快速完成初稿,虽然写出来的东西可能连自己都看不下去,但重要的是先把初稿完成并发出去,之后就在被工程师不断鄙视的 Review 过程中,获得有用的信息,最终按时完成项目。
这是不是一个好方法,我不加评论。还是放松一下心情,看看下面的文章吧。
以下内容为转载,感谢译者和原作者的分享。
译者: happydeer 原作者: Jeff Atwood
在浏览CouchDb.com网站的时候,我偶然看到了Damien Katz写的关于技术文档写作过程的描述,觉得非常滑稽。大家知道,现实情况是这样的:
欢迎来到技术文档的世界!
你的处境跟其他的文档工程师没啥不一样。技术文档的写作过程如下:
-
询问程序员那鬼东西是怎么工作的。
-
沉默一片……大家都聋了吗?
-
听见蛐蛐在叫……
-
听见风吹草动的声音……
-
不管啦,开始写点东西出来。任何东西都行。
-
把写出来的东西给程序员看。
-
在一边看着:程序员发现你写的东西完全不得要领,很抓狂。
-
在程序员斥责你的时候,他也会抛给你一些有价值的技术信息。
-
收集这些“珍品”,因为这些是你能得到的唯一可靠的技术信息。
-
拼命把这些信息组织在一起,使它们具有可读性,并且在技术上也是准确的。
-
跳回到第6步。
好吧,你不是做文档工程师的料。没关系,我也不行。不过,人们已经在努力把这件事做得更好。我也会继续努力的。
在我的职业生涯里,上述两种角色我都曾扮演过。这事挺有趣的,因为它是真的。我还记得,我在Mike Pope的博客上看到过极其相似的描述。
译文地址:blog.csdn.net/happydeer/article/details/14045627
原文地址:www.codinghorror.com/blog/2006/08/how-to-write-technical-documentation.html
如方便,请发email: ada.suzhou@foxmail.com