如何写技术文档

偶尔看到一篇有趣的文章,诙谐地描述了技术文档的写作过程。

我相信在实际工作中并非都是这样的,但这确实是有可能出现的情况:由于程序员太忙、不重视、认为 TW 应该具备和程序员一样的技术水平等各种原因,造成 TW 很难获取撰写技术文档所需要的信息。

这时候 TW 应该如何应对,相信大家各有各的方法。

曾经有人建议过一个方法: 在无法获得信息的情况下,先尽自己的努力快速完成初稿,虽然写出来的东西可能连自己都看不下去,但重要的是先把初稿完成并发出去,之后就在被工程师不断鄙视的 Review 过程中,获得有用的信息,最终按时完成项目。

这是不是一个好方法,我不加评论。还是放松一下心情,看看下面的文章吧。

以下内容为转载,感谢译者和原作者的分享。

译者: happydeer    原作者: Jeff Atwood

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

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

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

  1. 询问程序员那鬼东西是怎么工作的。

  2. 沉默一片……大家都聋了吗?

  3. 听见蛐蛐在叫……

  4. 听见风吹草动的声音……

  5. 不管啦,开始写点东西出来。任何东西都行。

  6. 把写出来的东西给程序员看。

  7. 在一边看着:程序员发现你写的东西完全不得要领,很抓狂。

  8. 在程序员斥责你的时候,他也会抛给你一些有价值的技术信息。

  9. 收集这些“珍品”,因为这些是你能得到的唯一可靠的技术信息。

  10. 拼命把这些信息组织在一起,使它们具有可读性,并且在技术上也是准确的。

  11. 跳回到第6步。

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

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

译文地址:blog.csdn.net/happydeer/article/details/14045627

原文地址:www.codinghorror.com/blog/2006/08/how-to-write-technical-documentation.html

 

7 条评论 次浏览

  1. Rola 的头像 Rola 说:
    不是有SME吗?写新文档,架构什么的可以和PO还有SA一起开个会讨论下嘛!架构定好后,SME要协助TW一起去完善内容,因为TW对feature的了解肯定没developer深嘛!如果这些都不能做到,这倒不失一个workaround
    Dan 于 2013-12-16 9:50:23 回复
    嗯,这不是经常出现的情况。只是 SME 不配合的某些极端情况下,可能出现的状况。:P
  2. Ada 的头像 Ada 说:
    你们都是大公司啊 还有SME,我就只能找产品经理协调拉^_^
    doria 于 2015/7/17 9:44:17 回复
    我们也是,找PM 和ME
  3. Ada 的头像 Ada 说:
    求个 Flare V5的license,用于个人学习,谢谢~~
    如方便,请发email: ada.suzhou@foxmail.com
    Dan 于 2013-12-16 16:41:53 回复
    V5? 直接去官网下载最新 V9 的的试用版啊,可以试用一个月。
    http://www.madcapsoftware.com/products/flare/
    Ada 于 2013-12-17 9:49:38 回复
    555~~~一个月过期拉,才看了几天,然后忙就没用 现在用不了了
  4. Grace 的头像 Grace 说:
    亲身体验,在摸不清头脑的时候就努力写下点什么,自己过一遍两遍。。。N遍,就会发现好像轮廓出来了~.~!
    Dan 于 2014-2-25 10:16:30 回复
    嗯,“努力写下点什么”的过程其实就是自己努力学习和了解产品的过程。:)
  5. ztt 的头像 ztt 说:
    你好,我也是一名technical writer,已经做了3年了。在无人指导的情况下自己摸索,看了这篇文章深有同感。 到目前为止还是感觉大部分都不重视这一块所以进行总不是那么顺利...
    Dan 于 2014-2-25 10:20:38 回复
    大家一起努力。我们 technical writer 工作的其中一个目标就是让大家对这一块逐渐重视起来。
  6. dashu123456 的头像 dashu123456 说:
    找项目经理获取软件需求说明书、概要设计说明书、详细设计说明书,过一遍,就会有头绪了
    Dan 于 2014-3-14 18:22:31 回复
    很好的方法,学会读文档和问问题是 Technical Writer 必须具备的技能。
  7. Coral 的头像 Coral 说:
    最有效的莫过于全程投入产品的设计、开发、测试,这样不仅了解技术,功能描述和场景定位也相当准确;如果再能亲自去开局或升级局点,甚好~
    Dan 于 2014-3-28 9:56:20 回复
    嗯,Coral 说得很好~ TW 不应该只是坐在电脑前干巴巴地写文档。
    lanlan 于 2014-10-7 0:30:21 回复
    哪有那么容易啊,我们项目的资料都是干巴巴的写,参与开发,测试过程是不可能的

留下评论/回复