Archive for the ‘技术写作’ Category

从高山阵屋看可获取性在技术文档中的重要性

2016年3月8日

笔者今年年初游览了日本名古屋附近的几个景点,其中尤以高山阵屋印象深刻。但凡参观过日本各种本丸御殿和天守阁的同学都会注意到,此类景点都会清楚的标明参观路线。殿中每隔一段距离就会在合适的地方标记“顺路”“归路”或者“上行”“下行”。因此,各个景点虽然游客不少,但都是井然有序。

...

七年了!中国技术传播还在“井喷”的路上?

2014年6月27日

今天是 2014 年 6 月 27 日。非常巧,今天想要分享一篇在七年前的今天(2007 年 6 月 27 日)发表于《科学时报》的关于中国技术传播的文章,名为《中国技术传播:“井喷”前的挑战》。

七年弹指一挥,中国技术传播在发展,在进步:

我们看到了从事技术传播的同行人数越来越多;

我们开始有了中国技术传播从业者的沙龙和研讨会;

我们看到国内高校开始开设相关课程以及与相关企业的合作讲学,比如北京大学软件与微电子学院开设“技术传播与翻译”方向专业硕士课程;

我们看到一些专业的技术传播公司的发展,看到了他们在通过微博,微信等方式发布关于技术传播的文章,促进行业交流发展;

我们也有了200多人的技术写作 QQ 群;

……

言简意赅

2014年4月1日

言语简练,意思完整,这几乎是评判所有写作好坏的重要标准之一。

对技术文档工程师而言,言简意赅更是我们写作的努力方向。冗长的行文,拖沓的表达,不仅增加之后的翻译成本,更为重要的是,浪费了用户宝贵的时间和精力,从而让用户对文档甚至对产品留下不好的印象。

如何做到言简意赅?“The Elements of Style” 的作者 E.B. White 和 William Strunk Jr. 给一个很好的回答:

...

技术写作实战(5)

2014年3月29日

请按照技术写作的要求修改下面的句子:

  1. The default value of the <duration> parameter of this JS function is 100.
  2. Remove the selected record from the list by clicking Drop.
  3. You can create your maintenance plan with Schedule Editor.
  4. Enter the record number that you want to search for.
  5. Click on Next (or press on the Enter key).

...

IBM 技术文档的质量标准

2014年3月21日

IBM 作为一家高大上的 IT 公司,对技术写作领域的影响也非常大,比如 DITA,比如技术写作规范,比如对技术写作人才培养(仅在上海,IBM 就有几十名技术文档工程师),等等。

那么,IBM 技术文档质量标准是什么?来看看 IBM 是如何定义高品质的技术信息内容的吧。

IBM 的 Corporate User Technologies Team 将高品质的技术信息概括为三个方面:

...

如何写技术文档

2013年12月12日

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

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

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

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

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

...

技术写作实战(2)

2013年11月1日

请按照技术写作的要求修改下面的句子:

  1. Enter your command in one line (i.e., without a line break).
  2. Measurements include weight, speed, distance, size,  length, etc. 
  3. e.g., you can set up a Tomcat server to host the web application.

...