从事技术传播的同学对这幅图一定不会感到陌生。这是 Darwin Information Typing Architecture (DITA) 的 LOGO,而 DITA 是 OASIS 发布的一套关于如何编写和发布技术信息的标准。
注意到了这个 LOGO 里的这只鸟了吗?它可是大有来历的!
...
从事技术传播的同学对这幅图一定不会感到陌生。这是 Darwin Information Typing Architecture (DITA) 的 LOGO,而 DITA 是 OASIS 发布的一套关于如何编写和发布技术信息的标准。
注意到了这个 LOGO 里的这只鸟了吗?它可是大有来历的!
...
笔者今年年初游览了日本名古屋附近的几个景点,其中尤以高山阵屋印象深刻。但凡参观过日本各种本丸御殿和天守阁的同学都会注意到,此类景点都会清楚的标明参观路线。殿中每隔一段距离就会在合适的地方标记“顺路”“归路”或者“上行”“下行”。因此,各个景点虽然游客不少,但都是井然有序。
...
大家在完成文档的 Draft 之后,如何进行文档 Review,收集反馈呢?
用邮件给相关人员发 PDF 文件应该是对文档进行评审并收集文档反馈的常用方式之一吧 (当然,还有召开 Review meeting 等其他方式)。
在发出 PDF 之后,如果文档的评审人员很多 (wide audience review),你是不是也有过被反馈邮件搞得晕头转向的时候?
...
今天是 2014 年 6 月 27 日。非常巧,今天想要分享一篇在七年前的今天(2007 年 6 月 27 日)发表于《科学时报》的关于中国技术传播的文章,名为《中国技术传播:“井喷”前的挑战》。
七年弹指一挥,中国技术传播在发展,在进步:
我们看到了从事技术传播的同行人数越来越多;
我们开始有了中国技术传播从业者的沙龙和研讨会;
我们看到国内高校开始开设相关课程以及与相关企业的合作讲学,比如北京大学软件与微电子学院开设“技术传播与翻译”方向专业硕士课程;
我们看到一些专业的技术传播公司的发展,看到了他们在通过微博,微信等方式发布关于技术传播的文章,促进行业交流发展;
我们也有了200多人的技术写作 QQ 群;
……
言语简练,意思完整,这几乎是评判所有写作好坏的重要标准之一。
对技术文档工程师而言,言简意赅更是我们写作的努力方向。冗长的行文,拖沓的表达,不仅增加之后的翻译成本,更为重要的是,浪费了用户宝贵的时间和精力,从而让用户对文档甚至对产品留下不好的印象。
如何做到言简意赅?“The Elements of Style” 的作者 E.B. White 和 William Strunk Jr. 给一个很好的回答:
...
IBM 作为一家高大上的 IT 公司,对技术写作领域的影响也非常大,比如 DITA,比如技术写作规范,比如对技术写作人才培养(仅在上海,IBM 就有几十名技术文档工程师),等等。
那么,IBM 技术文档质量标准是什么?来看看 IBM 是如何定义高品质的技术信息内容的吧。
IBM 的 Corporate User Technologies Team 将高品质的技术信息概括为三个方面:
...
请按照技术写作的要求修改下面的句子:
...
国外很多大学的课程都会在后面加上个 101,表示这是该专业或领域的入门课程。Content Strategy 101,自然就表示这是 Content Strategy 的基础知识。
...
偶尔看到一篇有趣的文章,诙谐地描述了技术文档的写作过程。
我相信在实际工作中并非都是这样的,但这确实是有可能出现的情况:由于程序员太忙、不重视、认为 TW 应该具备和程序员一样的技术水平等各种原因,造成 TW 很难获取撰写技术文档所需要的信息。
这时候 TW 应该如何应对,相信大家各有各的方法。
曾经有人建议过一个方法: 在无法获得信息的情况下,先尽自己的努力快速完成初稿,虽然写出来的东西可能连自己都看不下去,但重要的是先把初稿完成并发出去,之后就在被工程师不断鄙视的 Review 过程中,获得有用的信息,最终按时完成项目。
这是不是一个好方法,我不加评论。还是放松一下心情,看看下面的文章吧。
...
如果自己不是技术文档工程师,大概也不会想到一个小小的技术文档写作领域,居然有这么多的技术写作工具可供选择。
随着 Software as a Service (SaaS) 的流行,技术文档写作工具是否也会开始云端化?
...