NetApp 文档风格指南
建议更改
PDF
我们的风格是对话和同理心，但我们始终保持专业精神，并达到这一要求。为 NetApp 文档编写内容时，请遵循以下准则。
以对话方式编写
在向专业同事解释时、像讲话一样书写。以对话的方式编写有助于您与受众建立联系。
| 过于正式 | 过于随意 | 我们的风格 |
|---|---|---|
如果您遇到BlueXP分层问题、可以在集群信息板上查看运行状况、以确定发生错误的原因。运行状况反映了 ONTAP 系统和服务连接器的状态。 |
如果发生故障、那就没什么乐趣了。尽管如此、您也不必担心、只需查看集群信息板即可了解发生了什么以及受到了什么影响。 |
出现故障时、BlueXP分层会在集群信息板上显示"失败"运行状况。查看状态以获取有关故障的信息。 |
在配置存储之前、您必须从BlueXP中发现ONTAP集群。发现完成后，您必须打开工作环境以配置存储。 |
您只需首先从BlueXP中发现ONTAP集群、然后打开工作环境以开始配置存储。轻松！ |
从BlueXP发现ONTAP集群后、打开工作环境以配置存储。 |
设置向导启动后，按照向导中的说明设置节点并将其加入集群。以下步骤将指导您完成向导中的步骤。 |
此时将显示设置向导（几乎像魔法一样），用于指导您完成设置节点并将其加入集群的简单过程。 |
按照设置向导中的说明设置节点并将其加入集群。 |
您可以从多种内容格式类型中进行选择，以安装和设置新系统。每种格式类型均提供完整的说明。选择与您喜欢的学习方式最匹配的格式类型。 |
您希望如何设置和安装系统？我们提供多种内容格式类型的说明，但只有您知道自己喜欢如何学习。 |
选择一种内容格式类型，以指导您完成系统安装和设置。 |
使用"水"
水份的功能增强了A 对话风格许多的摘要都很容易理解和翻译。
展开以了解更多信息
-
使用这样的、易于理解和翻译的、易理解的、易理解的、易理解的、易理解的、易理解的
不是
您是
不是
我们是
不是
是的
不是
让我们来看看
没有
我们将(如果需要未来时态)
不会
不会（如果需要未来紧张）
请勿
您将（如果需要应对未来的紧张情况）
-
请勿使用这些难以理解和翻译的合同：
会的
应该有的
不会
不应该这样做
本可以做到的
不可能
只需编写即可
避免使用大而令人困惑的词语。保持简单。您正在向专业同事解释某些内容、而不是展示您的词汇。
而不是这样："解除用户与您的NetApp云中心帐户的关联。"
执行此操作："从您的NetApp云平台帐户中删除用户。"
最少写入
短而简单的句子使内容更易于阅读或扫描。可以稍后使用较长的句子、但请使用较短的句子。就像这样。
而不是这样："要在AWS中的Cloud Volumes ONTAP系统与其他网络中的ONTAP系统之间复制数据、您必须在Amazon VPC与其他网络(例如Azure vNet或您的公司网络)之间建立VPN连接。"
执行此操作："网络之间的数据复制需要通过VPN进行连接。例如、在您的Amazon VPC和企业网络之间、或者在AWS和Azure之间。"
问自己以下问题：
-
目前，用户是否需要此内容？
-
用户界面是否已经足够好地引导用户？如果不是、可以简单地添加哪些额外指导？
-
我能否用较少的语言来呈现内容，而不会听起来过于正式或过于随意？
-
我可以缩短或简化一句长句，还是将其分成两句或更多句话？
-
是否可以使用列表使内容更可扫描？
-
是否可以使用图形来增加或替换文本块？
正在写入
避免被动语音是技术写作的一项标准规则、但当您想要进行对话时、使用主动语音尤为重要。
活动语音
使用主动的声音、使句子主体执行动词的动作。这通常意味着动词遵循句子的主题。主动式语音可让写入内容清晰明了。除非您有特定的理由使用被动语音、否则请将主动语音和地址用户直接用作"您"。
下面是一些良好的主动语音书写示例。如下所示：
-
在部署第一个集群之前、请提供所需的权限。
-
如果您未正确关闭系统、则界面会显示警告消息。
-
NetApp 已收到合同。
被动语音
在被动语中，操作者不清楚：
-
如果系统关闭不正确，则会显示一条警告消息。
-
NetApp 获得了合同。
在以下情况下使用被动语音：
-
您不知道谁或谁执行了该操作。
-
您希望避免因操作结果而责备用户。
-
您不能绕着它写文章、例如某些前提条件信息。
迫切的心情
在用户操作列表的步骤、指令、请求和标题中使用命令心情：
-
在"工作环境"页面上、单击发现并选择ONTAP集群。
-
'旋转凸轮把手、使其与电源齐平。'
考虑使用强制语音来取代被动语音：
而不是这样："在部署第一个集群之前，必须提供所需的权限。"
执行此操作："在部署第一个群集之前，请提供所需的权限。"
避免使用强制性语音将步骤嵌入到概念和参考信息中。
有关其他动词约定，请参见：
编写一致的内容
"在向专业同事解释内容时、像说话一样书写"对每个人来说都是不同的。我们专业而对话的风格有助于我们与用户建立联系、并增加多个作者之间出现细微不一致的频率：
-
重点关注内容清晰易用。如果所有内容都清晰且易于使用、则细微的不一致无关紧要。
-
在您撰写的页面中保持一致。
-
请始终遵循中的准则 为全球受众撰写。
使用包容性语言
NetApp 认为，其产品文档不应包含歧视，排他的语言。我们使用的词语可以在与客户建立积极的关系或孤立客户之间发挥作用。尤其是对于文字，影响比意图更重要。
在为 NetApp 产品创建内容时，请避免使用可被解释为有损人格，具有种族，性别歧视或其他压制性的语言。相反，请使用可供需要使用文档的每个人访问并欢迎使用的语言。例如，请使用 " 主 / 从 " 代替 " 主 / 从 " 。
使用以人为本的语言、首先指的是人、其次是残疾。
不要使用他、他、他、她、她、 或其在通用引用中。而是：
-
重写句子以使用第二个人(您)。
-
重新写入句子、使其具有复数名词和代词。
-
使用"the "或"A"代替代词(例如、"文档")。
-
指某人的角色(例如、读者、员工、客户或客户)。
-
使用术语"个人"或"个人"。
被视为包容性或排他性的词语和短语的示例
| 包容性示例 | 专属示例 |
|---|---|
主/辅 |
主/从 |
允许列表 |
白牌 |
阻止列表 |
黑名单 |
停止 |
终止 |
停止响应 |
稍等 |
结束或取消 |
中止 |
工时 |
工时 |
开发人员需要访问其开发环境中的服务器、但不需要访问Azure中的服务器。 |
开发人员需要访问其开发环境中的服务器、但不需要访问Azure中的服务器。 |
盲人 |
视力受损 |
视力较弱的人 |
视力受损 |
达到关键点
每个页面都应以对用户最重要的内容开头。我们需要了解用户正在尝试做什么、并专注于帮助他们实现这一目标。我们还应在句子开头添加关键字、以提高扫描能力。
请遵循以下一般性句子指南：
-
请保持精确。
-
避免填充词。
-
请简短。
-
使用带格式的文本或项目符号列表突出显示要点。
达到目的的示例
| 很好的例子 | 错误示例 |
|---|---|
如果您的企业有严格的安全策略、请使用传输中数据加密在不同网络中的NFS服务器之间同步数据。 |
Cloud Sync可以使用传输中数据加密功能将数据从一台NFS服务器同步到另一台NFS服务器。如果您对通过网络传输数据制定了严格的安全策略、则加密数据会有所帮助。 |
创建包含您最常用的样式、格式和页面布局的文档模板、从而节省时间。然后、在创建新文档时使用模板。 |
模板为创建新文档提供了一个起点。模板可以包括您经常使用的样式、格式和页面布局。如果您经常对文档使用相同的页面布局和样式、请考虑创建模板。 |
Astra Control提供了三种操作模式、您可以将这些模式分配给用户、以便仔细控制Astra Control与云环境之间的访问。 |
通过Astra Control、您可以为AWS帐户中的用户分配三种操作模式之一。通过这些模式、您可以根据IT策略仔细控制Astra Control与云资产之间的访问。 |
使用大量可视化信息
大多数人都是视觉学习者。使用视频、图表和屏幕截图来改进学习、细分文本块、并为用户提供任务说明中的直观提示。
-
包括描述下图的前置句子："下图显示了背面板上的交流电源LED。"
-
请将图示位置参见"以下"或"前面"、而不是"上面"或"下面"。
-
在嵌入式视觉效果上使用可选文字。
-
如果视觉效果与步骤相关、请在步骤后立即加入视觉效果、并缩进以与步骤编号对齐。
屏幕截图最佳实践：
-
每个任务最多包含5个屏幕截图。
-
不要在屏幕截图中包含文本。请改用编号的编号。
-
请谨慎处理您选择包含的屏幕截图。屏幕截图可能会很快过期。
视频或动画的最佳实践：
-
视频长度应少于5分钟。
创建可帮助用户实现目标的工作流
用户可以阅读我们的内容来实现特定目标。用户希望找到所需的内容，实现目标，并返回家中与家人联系。我们的工作不是记录产品或功能。我们的工作是记录用户目标。工作流是帮助用户实现目标的最直接方式。
工作流是一系列步骤或子任务，用于说明如何实现用户目标。工作流的范围是一个完整的目标。
例如，创建卷的步骤不是工作流，因为创建卷本身并不是一个完整的目标。将存储提供给 ESX 服务器的步骤可以是一个工作流。这些步骤不仅包括创建卷，还包括导出卷，设置任何必要的权限，创建网络接口等。
工作流源自客户用例。工作流仅显示实现目标的一种最佳方式。
根据用户目标组织内容
根据用户尝试实现的目标组织内容、帮助用户快速查找信息。此标准适用场景文档站点的目录(导航)以及站点上显示的各个页面。
按如下方式组织内容：
- 左侧导航栏中的第一个条目（高级）
-
围绕用户尝试实现的目标组织内容。例如、网站导航中的第一个条目可能是"开始使用"或"保护数据"。
- 文档站点导航中的二级条目(中等级别)
-
围绕构成目标的广泛任务组织内容。
例如、"开始使用"部分可能包括以下页面：
-
准备安装
-
安装和设置<product name>
-
设置许可
-
接下来可以执行的操作
-
- 单个页面（详细级别）
-
在每个页面上、围绕构成广泛任务的各个任务组织内容。例如、用户为安装或设置灾难恢复所需准备的内容。
一个页面可以描述一个或多个任务。如果有多个任务、则应在页面的单独部分中对其进行说明。每个部分都应侧重于广泛任务的一个学习或做方面。其中可能包括完成任务所需的一些概念和基于参考的信息。
为全球受众撰写
我们的文档供许多主要语言不是英语的用户阅读。我们使用神经机器翻译工具或人工翻译将内容翻译成其他语言。为了支持全球受众、我们编写了易于阅读和翻译的内容。
请遵循以下准则为全球受众编写：
-
写简短的句子。
-
使用标准语法和标点符号。
-
一个词表示一个含义，一个词表示一个含义。
-
使用常见的收缩。
-
使用图形来澄清或替换文本。
-
避免在图形中嵌入文本。
-
避免在一个字符串中包含三个或更多名词。
-
避免出现不明确的前体。
-
避免使用术语，语言和比喻。
-
避免使用非技术示例。
-
避免使用硬返回和空格。
-
不要使用幽默或讽刺。
-
不要使用歧视性内容。
-
不要使用带有性别偏见的语言、除非你是为特定的个人编写的。
A 到 Z 准则
首字母缩略语和缩写词
使用众所周知的首字母缩略语和缩写词来熟悉情况、但要避免使用可能会对清晰度和可查找性产生负面影响的模糊缩略语和缩写词。有关缩写词和缩略语的其他约定，请参阅 "Microsoft 写入模式指南"。
主动语音(与被动语音)
请参见 正在写入。
荣誉
正确使用时、训言是一种强大的工具。他们可以提请注意重要信息、提供有用的提示或警告用户潜在的危险。过度使用时、它们会失去影响、并可能导致用户疲劳。以下是确保有效使用警告的一些准则。
使用以下标签将警告与主要内容流分开：
-
注意使用"注意"突出显示必须从文本其余部分中脱颖而出的重要信息。但是、请避免使用"已知良好"信息的注释、因为这些信息对于用户理解或完成任务并不重要。注释的目的是提请读者注意他们可能会忽略的关键点。
-
提示提示应谨慎使用(如果有)、因为我们的政策是默认记录最佳实践信息。如有必要、请使用提示突出显示有助于用户更轻松高效地使用产品或完成步骤或任务的最佳实践信息。提示应提供有助于增强用户体验的有用建议或快捷方式。
-
小心谨慎警告用户可能导致不良后果的情况或操作、包括人身伤害或设备损坏。应注意用户必须避免的潜在危险、以防止伤害或中断。
-
最佳实践使用最佳实践突出显示完成任务或使用产品的最佳方式。这些不仅是建议、而且是经过专家或行业标准验证的策略。
-
*什么是最佳实践？*这是一项针对具体任务的可行战略、可提供明确的优势、并有可靠的来源作为后盾。
-
*何时可以使用它们？*您可以对所有内容类型和所有受众使用最佳实践。与提示一样、请谨慎使用、以保持其重要性。
-
*如何设置格式？*以一致、用户友好的格式展示最佳实践。这可能是项目符号列表、编号列表或段落、具体取决于上下文。
-
-
仅使用支持的警告。不支持任何其他格式。
-
避免过度使用警告。过度使用可能会导致用户跳过这些重要部分、因为他们将其视为我们文档的"垃圾箱"。
-
根据经验、每页最多可显示3条警告。
-
在警告中提供清晰简洁的信息。信息应简明扼要、便于用户快速了解所提供信息的重要性。
-
避免在表中使用AsciDoc警告。如果需要将内容标识为注释、提示或小心、请使用注：、提示：、 或警告：作为文本的内嵌导入。
之后(与"一次")
-
使用“之后”指示时间顺序：“插入计算机后打开计算机。”
-
使用"一次"仅表示"一次"。
此外
-
使用 "al又 " 表示 " 另外 " 。
-
不要使用"同时"来表示"或者"。
和 / 或
如果有一个术语，请选择更精确的术语。如果两个术语都不比另一个术语更精确、请使用"和/或"。
作为
请勿使用"AS "表示"因为"。
使用(与"使用"或"使用"相对)
-
如果正在使用的实体主题为"您可以使用"组件"菜单将新组件添加到存储库、请使用"通过使用"。
-
您可以用"使用"或"与"开头一句话、产品名称有时也可以使用此句话："使用SnapDrive、您可以在Windows环境中管理虚拟磁盘和Snapshot副本。"
可以(与"可能"、"可能"、"应该"或"必须"相对)
-
使用"CAN"表示功能："您可以在此操作步骤期间随时提交更改。"
-
使用“可能”表示可能：“下载多个程序可能会影响处理时间。”
-
请勿使用"可以"、因为"可以"可能表示功能或权限、这种说法不明确。
-
使用"应"表示建议但可选的操作。请考虑使用替代短语、例如"我们建议"。
-
避免使用"必须"、因为它是 被动。请考虑使用强制性语音将此思想重新表达为一个指令。如果您使用"必须"、请使用它来指示所需的操作或条件。
大写
几乎所有内容都使用句子形式的大写（小写）。仅资本化：
-
句子和标题的第一个词，包括表标题
-
列出项的第一个词，包括句子片段
-
正确的名词
-
文档标题和字幕（将五个或更多字母的所有主要词和前言大写）
-
UI 元素，但前提是它们在界面中大写。否则，请使用小写。
注意事项
请参见 荣誉。
收缩
使用 … 收缩 作为对话写作的一部分。
确保(与"确认"或"验证"相对)
-
使用"ensure (确保)"表示"to make sure (确保)"。 根据需要包括"该"："确保插图周围有足够的空白空间。"
-
切勿使用"确保"暗示承诺或保证："使用云管理器确保您可以在ONTAP集群上配置NFS和CIFS卷。"
-
如果您的意思是用户应仔细检查已存在或已发生的内容、请使用"确认"或"验证"："验证是否已在集群上设置了NFS"。
图形
请参见 使用大量可视化信息。
如果不是
请勿单独使用"如果不是"来引用上一句：
-
而不是这样："计算机应关闭。否则、请将其关闭。"
-
* 执行此操作 * ： " 验证计算机是否已关闭。 "
IF (与"是否"或"何时")
-
使用"if"表示条件、例如在"if this、Then Th那"(如果这种情况、则为该情况)中。
-
如果存在明示或默示的"或非"条件、请使用"是否"。为了便于翻译，通常最好将 " 是否 " 替换为 " 是否 " 。
-
使用"何时"表示时间已过。
迫切需要的声音
请参见 正在写入。
未来的功能或版本
请勿提及即将发布的产品版本或功能的时间或内容、只能说某个功能"当前不受支持"。
知识库文章：引用
如果适用，请参阅内容中的知识库（ NetApp 知识库）文章。对于 " 资源 " 页面和 GitHub 内容，请将此链接置于运行文本中。
列表
信息列表通常比文本块更易于扫描和吸收。通过以列表形式呈现复杂信息，考虑简化复杂信息的方法。下面是一些一般准则，但请根据您的判断：
-
确保列表的原因清晰。使用完整的句子，带有冒号的句子片段或标题来介绍此列表。
-
在列表中使用列表时、请将结构限制为最多两个深度级别、以保持清晰度和可读性。如果您发现自己需要更高级别的内容、请考虑重新组织内容、使用户更易于导航和理解。
-
任何列表(包括嵌套列表)都应包含2到7个条目。通常，每个条目中的信息越短，您可以添加的条目越多，而列表仍可扫描。如果列表包含多个包含嵌套列表的条目、请考虑使用分区或块标题将整个内容划分为更多可消耗的块。
-
列表条目应尽可能可扫描。避免出现妨碍列表条目可扫描的文本块。
-
列表条目应以大写字母开头，列表条目应以格式并行。例如，使用 noun 或 verb 启动每个条目：
-
如果所有列表条目都是完整的句子，请以句点结尾。
-
如果所有列表条目都是句子片段、请勿以句点结尾。
-
-
列表条目应按逻辑顺序排列，例如按字母顺序或按时间顺序排列。
本地化
请参见 为全球受众撰写。
极简主义
请参见 最少写入。
数字
-
对于 10 ，使用阿拉伯语数字，并且所有数字均大于 10 ，但以下情况除外：
-
如果一个句子以数字开头，请使用一个词，而不是阿拉伯语数字。
-
请使用词语（而不是数字）表示大致数字。
-
-
对于小于 10 的数字，请使用单词。
-
如果一个句子包含小于 10 且大于 10 的数字的混合，请对所有数字使用阿拉伯语数字。
-
有关其他编号约定、请参见 "Microsoft 写入模式指南"。
政策
我们会记录 NetApp 产品以及 NetApp 产品与第三方产品之间的交互。我们不会记录第三方产品。我们不应需要将第三方内容复制并粘贴到文档中，也不应复制和粘贴到文档中。
前提条件
前提条件用于确定用户在启动当前任务之前必须存在的条件或必须完成的操作。
-
使用标题(例如"前提条件"、"开始之前"或"开始之前")确定内容的性质。
-
如果有必要，请使用被动语音作为前提条件：
-
"必须在集群上设置NFS或CIFS。"
-
"要将集群添加到Cloud Manager、您必须知道管理员用户帐户的集群管理IP地址和密码。"
-
-
根据需要阐明前提条件："必须在集群上设置NFS或CIFS。您可以使用System Manager或命令行界面设置NFS和CIFS。"
-
请考虑其他显示信息的方式，例如，将内容重命名为当前任务的第一步是否合适：
-
前提条件："在部署第一个集群之前、您必须具有所需的权限。"
-
步骤："提供部署第一个集群所需的权限。"
-
"以前"(与"以前"、"以前"或"以前"相对)
-
如有可能，将"以前"改为"以前"。
-
如果您不能使用"之前"、请使用"之前"作为一个词来表示较早发生的事件或重要性更高的事件。
-
使用"上一步"指示在未指定的时间之前发生的事件。
-
使用"前面"表示之前立即发生的事情。
标点符号
保持简单。一般来说，一个句子中包含的标点符号越多，要理解的脑细胞就越多。
-
在包含三个或更多项的叙述列表中、在连词("和"或"或"或")之前使用一个连续逗号(牛津逗号)。
-
限制使用分号和冒号。
-
除非另有说明，否则请遵循中详细介绍的语法，标点符号和拼写约定：
自此
使用"自"表示时间已过。不要使用"自"来表示"因为"。
(与"哪个"或"谁"相对)
-
使用"that (that)"(不带结尾逗号)可引入句子含义所需的子句。
-
即使句子在英语中很清晰、但不使用"that (确认计算机已关闭)"、也可以使用"that (该)"。
-
使用"which (加后逗号)可引入添加支持信息但句子含义不需要的子句。
-
使用"谁"来引入提及人员的条款。
商标
我们的大多数技术内容中不包含商标符号、因为我们模板中的法律声明已经足够。但是，我们在使用时会遵循所有使用规则 "NetApp 商标术语"：
-
使用商标术语（带或不带符号）仅作为形容词，而不是名词，动词或文字。
-
请勿使用缩写、用联苯或意大利字母来表示商标术语。
-
请勿将商标术语复数。如果需要复数形式，请使用商标名称作为可修改复数名词的词。
-
请勿使用商标术语的所有形式。在一般意义上使用公司名称时，您可以使用 NetApp 等公司名称的形式，而不是商标术语。
用户界面
在记录用户界面时、请尽可能依靠该界面来指导用户。
记录用户界面时、请使用简单的模拟方式。
Details
-
假设用户在阅读内容时正在使用界面：
-
请勿逐步引导用户完成向导或屏幕操作。只需从界面中调用不明显的重要内容即可。
-
请勿包含"单击确定"、"单击保存"或"已创建卷"或执行任务的人员可以明显看出的任何其他内容。
-
假设成功。除非您希望某个操作在大部分时间都失败，否则请勿记录故障路径。假设接口提供了正确的指导。
-
-
完全不要使用"单击"。请始终使用"select (选择)"、因为该词涵盖了鼠标、触摸、键盘和任何其他选择方式。
-
将内容重点放在可解决客户使用情形的工作流上，并将用户引导到界面中的正确位置来启动工作流。
-
始终记录实现用户目标的一种最佳方式。
-
如果工作流需要做出重大决策，请务必记录决策规则。
-
大多数情况下，请使用大多数用户所需的最少步骤数。
避免记录到需要为 UI 元素命名的粒度级别。
Details
借助界面引导用户完成交互的具体内容。如果必须获取该特定名称，请为元素上的标签命名。例如、"选择所需卷"或"选择"使用现有卷"。 无需命名菜单、单选按钮或复选框、只需使用标签即可。
对于用户必须选择的图标，请使用图标的图像。不要试图说出它的名字。此规则适用场景图标包括箭头，铅笔，齿轮， kabob ， HAMBURGER ， 等等。
在标识标签时，请遵循用户界面使用的拼写和大写字母。
Details
如果标签后跟省略号，则在为对象命名时不要包含省略号。鼓励开发人员对用户界面标签使用标题样式的大写字母，以便于编写。
请谨慎使用屏幕截图。
Details
偶尔的屏幕截图("屏幕截图")可帮助用户确保在工作流期间启动或更改界面时、他们处于界面的正确位置。请勿使用屏幕截图显示要输入的数据或要选择的值。
while (与"虽然")
-
使用"while (同时)"表示某个事件正在及时发生。
-
使用"虽然"表示在几乎同一时间或在其他活动之后不久发生的活动。