Archive for the ‘写作风格’ Category

言简意赅

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).

...

技术写作实战(4)

2014年2月25日

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

  1. The data integrity is checked by the scheduler.
  2. The following features can be found in this release.
  3. The error message can be removed by clicking Ignore.
  4. Verification of the digital signature is performed in the next step.
  5. Click Done
    The connection is now set up.
  6. The maintenance report is generated monthly.

...

技术写作实战(3)

2013年11月29日

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

  1. Do not turn off the computer when the application is still running. Doing so will stop all the tasks in process.
  2. This section will describe the configuration parameters.
  3. When the function returned a value, the loop escapes.
  4. When the function returns a value, the loop will escape.
  5. Enter all the required information, and then click Next. The confirmation screen will display.
  6. The following defects were fixed in this release.
  7. If you selected Reset in the previous screen, the current screen displays the default settings.

... 

技术写作实战(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.

...

技术写作实战(1)

2013年10月25日

学习技术写作最直接有效的方法就是通过实例了解技术写作的风格和规范。开辟一个技术写作实战系列,由简入深地累积一些关于技术写作风格的知识。

开始吧~

请按 Technical Writing 的要求修改下面的句子:

...

技术写作里的 En Dash 和 Em Dash

2013年9月2日

一致性(Consistency)是技术写作里最重要的原则之一。即使是标点符号,也应保证其使用的一致性。

小小的横线,使用上也有区别。这里说的横线也就是 En Dash 和 Em Dash。

虽然这是技术写作里很基础的东西,还是在博客里记录一下,算是一个备忘吧。

...

文档中 Copyright 的意思和正确写法

2013年7月20日

在所有对外发布的技术文档中,一定都会有 Copyright。作为技术文档工程师,在我们需要加入或修改版权信息的时候,可能大都是从模版或者以前的文档中拷贝过来,然后修改一下时间。

那么,这个 Copyright 是什么意思,我们是不是清楚它的正确写法呢?

在这篇 Blog 里介绍和记录一下吧。

...

每个公司都需要自己专有的 Writing Style Guide 吗?不!

2013年7月2日

每个公司都需要Writing Style Guide来规范技术写作吗?
Dan:嗯,我认为是的。一个公司的技术文档,特别是面向客户的 产品文档,很大程度上体现了一个公司的专业性。如果没有一个统一的Writing Style Guide作为指导,不同的技术文档作者在写作的时候就没有统一的规范,也就不能保证写作风格的一致性。最终呈现在用户面前的就可能是一份格式和表达不 一,显得很不专业的产品手册。如果是几个作者合作同时为一个产品开发文档,就更需要有一个Writing Style Guide来进行规范了。

那么,每个公司都需要编写和维护属于自己公司的Writing Style Guide吗?
Dan:这个……我觉得,不需要。

为什么呢?前面不是说Writing Style Guide很重要吗?

...

It's 还是 its?这真的是一个问题?

2013年6月4日

以前一直以为It's和Its这么一个简单的语法问题,应该不会有人会弄错。可是在现实中,在需要使用its的地方却用了it's,这个错误在我帮工程师review文档的时候已经出现过不只一次,之前认为这应该只是个笔误吧。

bob's quick guide to its and it's from angry flower

...