言简意赅
用简短的话语表达丰富的想法。现代设计以简约主义为基础,我们在表达观点的时候,应尽量做到言简意赅。
示例:
Bad | If you're ready to contribute to our community as an individual developer, contact us by sending an email. |
Good | Ready to contribute? Feel free to contact us. |
像日常对话般行文
我们表达的方式就如日常中正常的对话一样,保持友好和亲切。
示例:
Bad | Invalid user ID! |
Good | Make sure that your user ID looks like this: [email protected]. |
Bad | This link is intended to redirect you to an online form. In the form, you can set a new password. |
Good | Clicking |
切忌过于随便或者正式的表达,尽量在两者之间取得合理平衡。
示例:
过于随便 | 恰如其分 | 过于正式 |
This is an awesome API that lets you collect data about what your users like most. | This API collects data about user preferences. | The API stated on this page enables acquisition of information pertaining to user preferences. |
贴近读者,体现友好性
采用面向读者的描述方式,例如,我们可以用you来指代a/the developer,贴近和读者的距离。在表达上,可以适当使用收缩词:it's、you'll、you're、we're、let's。
示例:
Bad | Before a developer integrates the SDK, the developer needs to download the services.json file, and add the file to the app directory of the project. |
Good | Before you integrate the SDK, download the services.json file, and add the file to the app directory of your project. |
礼貌是件好事,但过度使用‘请’,就显得过于‘生分’。
示例:
Bad | To view the document, please click View. |
Good | To view the document, click View. |
一般而言,当发生异常或失败,需要用户进行额外操作(如重试或联系客服)而给用户带来不便时,可以使用please表示委婉礼貌的语气。
示例:
XXX error. Please try again later.
Your application is rejected. Please contact our customer service.
切中要点
重要的事优先(first things first)。将关键字、重要信息置前,方便读者基于该信息判断是否继续浏览。
示例:
Bad | Templates provide an entry for creating new apps. A template can include the styles, formats, and page layouts you use most often. You're advised to create a template if you often use the same page layout and style for apps. |
Good | Save time by creating an app template that includes the styles, formats, and page layouts you use most often. Then use the template whenever you create a new app. |
遵循最小化原则
给读者提供恰如其分的信息,帮助TA们正确地做出决策。信息应不多不少,同时去除多余的字和词。
示例:
Bad | The Recommended graph option provides the function of recommending graphs that are likely to represent your data well. This option could be helpful if you want to visually represent data but you're not sure how to do it. |
Good | Use the Recommend graph option to create a graph that's just right for your data. To create a graph that's just right for your data, use the Recommend graph option. |
修改弱意表达
大多数时候,尽量以动词开头,告诉读者具体的任务。如果不是必要,删除诸如“you can”、“there is”、“there are”、“there were”等弱意表达。
示例:
Bad | You can use scaleControl to specify whether to display the scale and use scaleControlOptions to set the scale unit. |
Good | Use scaleControl to specify whether to display the scale and scaleControlOptions to set the scale unit. |
避免提出过度的主张或公布未来的功能特性
避免对产品、服务提出过度或无依据的观点主张。同时,尽量避免试图在文档中公布尚不支持的特性功能或尚未发布的产品。
示例:
避免描述尚未支持的功能:
Bad | Callback invoked when the street view is ready for use. (Currently, APIs related to street view are not supported.) |
Good |
|
在无确凿论据支持的情况下,避免过度声明主张:
Bad | …. There's no quicker and safer way to do this than with the Account Kit's ID-based two-factor authentication…. |
Good | …. The Account Kit provides users quick, safe onboarding experience with two-factor authentication…. |
合理凸显自身价值
措辞合理、准确。务必遵守当地广告法、行业公平竞争规定等,并且各个论点要有事实数据支撑。
在使用下表列出的典型词汇或类似词汇时,请重点查验。
敏感词汇 | 使用备注 |
显性表示超越同行的词汇,如: first No.1 | 需要有权威机构的证明或统计支撑。 |
隐性表示超越同行的词汇,如: best top industry-leading | |
表“独此一家”的词汇: unique unparalleled unpeered unequalled | 符合市场当前状况。如果市场情况发生了变化,要根据最新市场情况修改表达。 |
表“最高级”的词汇: highest lowest most | 如果不确定,可以加限定词进行规避。例如,nearly the most advanced |
表“极限”的词汇: ultimate extreme | 需说明限制条件。 |
24/7 anytime | 在当地的服务体系,是否能支持24/7、anytime,要与Service Agreement一致。 |
避免知识产权风险
对于某些在行业中存在通用叫法的产品、功能、特性、技术等相关关键术语,可以直接使用行业内的通用表达。
不直接使用行业中已注册商标的功能、特性、技术名称等专有名词。也不对特定厂商及其产品进行描述,尤其是比较性的描述。
如非必要,避免直接引用特定厂商或其他网站的短语和句子。否则,需提供明确的相关参考和引用说明。
注:本文观点参考了行业的一些规范,包括微软风格指南、Google开发者资料风格指南等。
标签:11,OpenHarmony,use,行文,示例,词汇,data,your,view From: https://blog.51cto.com/u_16052003/9116385