| VB 源码 | VC 源码 | ASP源码 | JSP源码 | PHP源码 | CGI源码 | FLASH源码 | 素材模板 | C 源程序 | 站长工具 | 站长教程 |

业界评论

业界资讯
业界评论

本类阅读TOP10

·手把手教你做传奇私服
·一个号码可以让你取消手机的任何服务项目
·破解MD5和SHA-1不意味密码破解
·探明Outlook无法发邮件的问题
·山东大学王小云教授成功破解MD5
·为什么要担心无线安全性
·开启雅虎替身邮 免受垃圾邮件骚扰
·Google正在考虑对RSS的支持
·将dvbbs送进地狱
·google联姻百度之后

站内搜索

技术写作——不要尝试去触犯你的读者

  原始出处:http://bbs.giltworld.com/dispbbs.asp?boardid=46&Id=4872

  与文学、政治、宗教、哲学等方面的作品不同,你通常是关注你的读者的技术和学术方面的,不可能也不在意你的读者国籍、性别、种族、宗教、文化、审美观和价值观。一个品牌型号的手机,男女老少都可能用;一台电脑,杀猪的和吃斋的都可能用,而你的关于大统一场的论文,可能被世界各国的同行们阅读。

  因此,你就必须避免因为这些社会的因素,使得你的技术论点被否定。即使你有着虔诚的宗教信仰,也不要带到你的技术文档中。你很可能冒犯你的读者。

  下面是一些你需要注意的。

  幽默

  幽默不是坏事,在交谈、讲课、讨论、客户接待甚至演讲中,偶尔带有一点幽默,可以显示出你的个性和魅力。但是,在技术写作中,还是尽量远离吧。

  你并不知道你的读者欣赏什么样的幽默,冷的热的,荤的素的,黑的白的。拿自己开涮,人家跟你不熟,那读者开涮,可能感觉冒犯;拿领导开涮,审核不能通过,拿同事开涮,可能遭到板砖;拿设备开涮,设备又不会笑,拿公司开涮,准备打铺盖滚蛋。

  个人见解

  尽量不要说“我认为”,“我建议”之类的话。我们谈的是技术文档特别是用户指导书,不是你的个人建议书,你所说的和所写的,代表了你所在的组织和团队。说严重点,用户指导书,代表了一个组织的承诺,而你个人是无法承担这种承诺的。即使是你的个人的建议和主张,也不要用“我建议”。

  另一种个人见解是以个人局部的经历来说事。“我们怎样怎样,你们怎么不行呢?”看,读者反感的是你后面那句。你可以把你做的工作、你的实践和你的经验共享出来。很多技术文档本身就是实践的产物。但是,请注意,不要强制性地让读者与你的实践进行比较对比,一旦发生比较,人就可能找借口的。你不可能把所有的借口都堵死。

  俗语或者俚语

  俗语或者俚语带有很强烈的地方色彩,一句“阿要辣油啊”就能知道说话的人是南京人,一个“杠杠的”就知道是东北人。

  使用俗语或者俚语可以拉进与读者的关系,也可能让读者有兴趣。但是,我还是那个理由,你的读者不仅仅是南京人,或者东北人,而可能是全国各地的人。“杠杠的”对于其他地区的人,很难理解。

  另一个可能性是,你的技术文章可能被翻译。而翻译俗语或者俚语很困难。(同样的,幽默也很难翻译。)

  有一位名人对国外的记者说,我是“和尚打伞无法无天”。本意是敢于创新,蔑视一切成规旧习。但是国外记者的却理解错了。连一个政要的话都被误解,你的技术文档能保证不被误解吗?

  激情的阐述

  技术总是会发展的,没有最好只有更好。所以,你的激情的阐述,可能会变得幼稚和可笑。

  当我们写到“小灵通的出现,使得广大的人民群众拥有一部移动电话的梦想成为现实”的时候,有没有想到2年后,小灵通又迅速地退市了呢?

  当我们写到“泰坦尼克号,将永不沉末”的时候,有没有想到,它现在还埋葬在大西洋底呢。

  所以技术文档不应该带有激情的阐述。你可以讨论小灵通的价格、使用方面的特性,也可以阐述泰坦尼克号的结构和设施。但不要代替你的读者下一个主观的判断。

  “广告”性语言

  读者在阅读你的文档时,实际上是在接受你的服务。而服务中的一个忌讳,是含有额外“额外付费”的暗示信息。相信大家都对电视中插播广告非常恼火吧?所以拒绝广告。

  你的广告性的语言,会被读者认为你在推销,虽然你确实在推销,推销你的技术和知识,但是,仅仅如此而已。不要让读者因为你的广告语言而厌恶你有用的知识和技术。如果要做广告,就名正言顺地做,在你的技术文档的封底、插页中做广告。不要带到文字中间。

  政治色彩

  算了,你要想被鬃局请去喝茶,尽管讨论好了。我只认为,政治变化比技术变化还要快,我想让我的文档能够长久被人看被人读。

  宗教色彩

  宗教只能在一个局部的地区实用。“出埃及”的典故不是每个人都知道。而由于宗教产生的冲突并不少。算了,我不想得罪任何人。

  时代色彩(topical)

  这个社会,技术发展很快,据说信息量每18个月翻上一翻。时代色彩的东西很快就会过时。

  而你说的今天的事情,等你的文档到读者手上,就成为过去。

  性别化

  性别化可能会让读者产生理解上的误区。

  有一则脑筋急转弯题目,说的是:警察小张有一个儿子小明,但是小明的父亲却不是小张。问为什么。答案,因为小张是儿子的母亲。可见,警察通常带有男性的特征。

  可能女权主义者会不高兴我的这段话。是的,性别化的另一个主要障碍就是女权主义者会不高兴。

  文化差异化

  文化差异,我建议大家看看其它的书籍,讨论这个方面的很多。我就不谈了。

  对读者评价

  对读者的评价要千万慎重。不要说一般不会评价读者,至少很多文档在说明文档阅读对象时会涉及,如“适合初学者”、“适合较高水平读者”“适合有3年以上C++编程经验的读者”。

  对读者的评价要用客观的和正面的词语,上述的例子是适合的。我推荐用有“n年经验”来评价你的读者。

  千万不要说“起点低”,“水平差”,这样只会触犯你的上帝。

  说了这么多,有几条建议,供参考:

  看看你的文档,把与技术无关的句子和段落统统删掉;

  用第二人称,或者职业称呼。不要用第三人称的代词,第三人称含有性别特征;

  尽可能把形容词删掉,能不用尽量不用;

  涉及时间的时候,用年月日来表示。不要用相对的时间(如“过去、今天、将来”之类)。




相关文章
  • 21招培养成功的心态,助你早日成功
  • Google的收购史清单
  • 十个让技术狂保持干劲的方法
  • 让你的博客炙手可热的101个奇思妙想
  • 要成为职业blogger所必须的10个条件
  • 创业者最容易犯的十个错误
  • 我学到的101点关于博客的东西
  • 对Google作恶手册
  • 如何让电脑里的系统日期和时间大变脸?
  • 全屏窗无提示关闭父窗口
  • 相关软件

  • DAO多线程的技巧  
  • 1个图标操作的技巧,1个图标有5种显示效  
  • VB使用技巧集锦  
  • 全部的VB技巧  
  • 图像处理大全,有许多的技巧(强力推荐)  
  • 图像技巧演示。  
  • 输出文本控制技巧  
  • 一个菜单操作技巧  



  • 月光软件源码下载编程文档电脑教程网站优化网址导航网络文学游戏天地生活休闲写作范文安妮宝贝站内搜索
    电脑技术编程开发网络专区谈天说地情感世界游戏元素分类游戏热门游戏体育运动手机专区业余爱好影视沙龙
    音乐天地数码广场教育园地科学大观古今纵横谈股论金人文艺术医学保健动漫图酷二手专区地方风情各行各业

    月光软件站·版权所有