内容风格指南
Please read Substrate to Polkadot SDK page first.
本指南重点介绍撰写技术文档的最佳实践，以及在为 Parity Technologies 产品和受众开发文档时应遵循的风格约定。 本指南的目标是帮助文档团队成员和任何有兴趣为文档做出贡献的人员撰写清晰、简洁且一致的材料。
本指南还包括专门针对此存储库的工作特性，以便活跃的 贡献者了解 构建者说明 部分中提供的信息。
如果您在本指南中找不到有关样式、语气或术语问题的答案，请查阅以下资源：
如果您在任何这些资源中都找不到答案，请打开一个 issue。
撰写引人入胜内容的一般指南
撰写吸引受众的内容有三个关键：
- 使用 第二人称 视角直接与读者对话。
- 尽可能使用 主动语态 和 现在时。
- 使用 口语化的语气，不要过于正式或过于随意。
视角
在大多数情况下，直接与读者对话。对于教程，使用第一人称复数——我们、我们、我们的、我们的——或第二人称视角。 由于教程提供了一种更具指导性的主题方法，因此与其他类型的文档相比，使用第一人称复数是一种更自然且更普遍接受的做法。
谨慎且有目的地使用第一人称视角。过度使用第一人称叙述可能会 压倒共享体验的感觉，并模糊读者的旅程。
除非出现在用户界面元素的文本中，否则不要使用“我”或“我”。
不要使用“我们”来指代 Parity 或 Substrate 开发者中心团队。例如，如果您正在记录 推荐的设置或实践，请使用“Parity Technologies 建议……”，而不是“我们建议……”。
被动结构
尽管有不要使用被动语态的格言，但在某些情况下，被动句式结构可能是合适的。 不要为了避免被动结构而将句子扭曲得支离破碎。被动语态确实有其作用，但要谨慎使用。
在编写有关软件时，人们常常会忍不住想从代码的角度描述正在发生的事情。 但是，几乎总会有一个怀揣目标或任务要完成的人类，他正在发起软件正在执行的活动。 如果您牢记这种人类的存在，您的写作将更加生动、更容易理解，并且更有趣。
缩写和口语化语气
缩写通常是可以接受的，因为它们使文档更具自然的口语化语气——至少对于英语使用者而言。 请注意何时以及为何使用缩写。
为了保持语气口语化但简洁，请遵守以下常识性指南：
- 尽可能使用常见、众所周知的词语。
- 不要使用华丽的语言或文学修辞词语和短语，例如“等等”、“尽管”、“迄今为止”或“因此”。
-
尝试在词语选择上做到精确。例如：
- 不要将“when”（暗示偶然性和时间）与“if”（暗示某事发生的可能性）互换使用。
- 不要使用引入歧义的短语。例如，不要使用“When the process completes...”而是使用“After the process completes...”。
- 仔细考虑词语选择，例如使用“since”（暗示一段时间）而不是“because”（暗示因果关系）或使用“once”（单次出现）而不是“after”（每次）。
-
避免使用陈词滥调的词语和短语，即使它们在实践中通常被认为是英语词语。例如：
- 不要使用“i.e.”，而应使用“that is”或改写句子以使含义清晰，无需额外的限定。
- 不要使用“e.g.”，而应使用“for example”。
- 不要使用“via”，而应使用合适的英语替代词，例如“by”、“through”或“using”。
- 不要使用“etc.”，而应使用“and so on”或修改内容以使该术语不必要。例如，修改为使用 such as 或 like 后跟一两个示例。
- 不要使用“caveat”，而应使用合适的英语替代词，例如“notice”、“caution”或“warning”。
-
避免添加不必要的词语或短语。例如：
- 不要使用“In order to”，而应直接使用“to”。
- 不要使用“as well as”，而应直接使用“and”。
- 不要使用“and then”，而应直接使用“then”。
- 避免使用行话、口语和习语。
-
避免使用副词和主观陈述。例如，不要使用包含 easily、rapidly、simply、quickly 等词语和短语。
- 确实更喜欢跳过教程的经验丰富的开发者……
- 我们可以快速测试这段代码是否按预期工作……
标题
所有标题级别都应遵循以下约定：
- 使用句子样式的大小写。
- 在适当的情况下，尤其是在教程和操作指南的上下文中，在标题中使用主动语态和现在时动词。
- 作为其包含内容的摘要。
- 尽可能避免使用 overview 和 introduction 等通用标题。虽然通用标题在概念上很有用，但它们不会为内容或导航体验增加任何价值。
- 始终包含内容。 标题后面永远不应该紧跟着另一个标题。 作为最佳实践，避免仅将标题用于导航。
- 避免在标题中使用代码、专有名词、特定于产品的术语和反引号。
- 使标题尽可能简洁，同时提供有关内容的有意义的线索。
限制标题级别
作为最佳实践，避免使用超过三个标题级别的信息层次结构。 大多数内容可以使用两个内部标题级别有效地组织，从而更容易导航和扫描相关主题。
主题标题
避免在标题和标题中使用动名词（以 -ing 结尾的动词）。 过程标题和标题应回答以下问题：您要尝试做什么？例如，如果 您要尝试做什么？ 的答案是 我想创建一个帐户，则文章标题应为 创建帐户。 在大多数情况下，概念和参考主题的名称使用名词短语，例如 事件挂钩。
列表
用标题、句子或以冒号结尾的片段来介绍列表。
对于必须按顺序完成的过程和步骤，使用 编号列表。对于不需要按顺序出现的项目，使用 项目符号列表。
使所有列表项的结构并行。例如，使用名词或以动词开头的短语开始列表中的每个项目。
项目符号
项目符号用于无序列表。 项目符号列表中项目的顺序可以暗示重要性，但通常所有列表项都是同级。
每个列表项都应以大写字母开头，并以句点结尾，除非所有列表项都是 单个词语或不超过四个词语的短语。 在列表中措辞项目时，使用并行结构。 例如，每个列表项都可能以动词、名词或动名词开头。
编号步骤
仅对过程中的步骤使用编号段落。 如果一个过程超过九个步骤，请务必考虑将其分解成带标题的子部分。理想情况下，每个过程或子任务应为三到六个步骤，不应嵌套子步骤，并且应在步骤后面使用未编号的段落来描述会发生什么——预期结果或结果——的嵌入段落最少。
不要将不同的操作合并到一个步骤中，除非两个操作完成了一个任务，例如“输入用户名，然后单击 下一步”。
代词
尽可能使用中性代词，例如“they”。 通常，您可以将任何名词从单数改为复数，以使主谓一致，并避免使用性别特定的代词，例如“he”、“him”、“his”或“she”、“her”、“hers”。
请注意非人称且可能模棱两可的代词，例如：
- all、another、any
- each、either
- few、many、neither、none、
- one、other
- same、several、some、such
- that、them、these、those
如果您使用任何这些非人称代词，请确保在句子中回答“of what？”、“of which？”或“as what？”。
术语和使用约定
本节涵盖常见的术语、样式和用法问题以及推荐做法。
Above 和 below
不要使用 above 来表示 earlier 或作为形容词放在名词前（the above section）或名词后（the code above）。使用超链接，或使用 previous、preceding 或 earlier。
不要使用 below 来表示 later 或作为形容词放在名词前（the below section）或名词后（the code below）。 使用超链接，或使用 later 或 the following。
例如： 使用前面的代码显示有关数据库的信息。 使用下面的代码显示有关数据库的信息。
日期和数字
使用 DD Mon YYYY 或 DD Month YYYY 格式表示日期。
在正文中，将零到九的整数拼写出来。 对于 10 或更大的数字，使用数字。 对于包含四个或更多数字的数字，使用逗号。 使用 more than 而不是 over（over 是一个空间术语）。
强调和警告
对于用户交互的用户界面元素，使用粗体格式，包括：
- 对话框标题
- 字段标签
- 按钮标签
- 用户界面中显示的选项
不要使用粗体、斜体或下划线来强调。如果文本需要比周围正文更多的关注， 请考虑将其作为独立的注释或提示进行隔离。
谨慎使用警告组件！ 它们通常会干扰读者的体验。问问自己，是否真的有必要通过添加注释、警告或提示组件来阻止读者的前进。
注释
指示中性或积极的信息，强调或补充正文中的重要要点。 注释提供的信息可能仅适用于特殊情况。例如，内存限制、设备 配置或适用于特定程序版本的详细信息。
提示
帮助用户将文本中描述的技术和程序应用于其特定需求。 提示建议可能不明显的替代方法，并帮助用户了解产品的好处和功能。 提示对于文本的基本理解不是必需的。
警告
建议用户如果未采取或避免特定操作，可能会导致数据丢失。
图片
图表和插图可以帮助读者形象化和内化复杂的想法和过程。 因此，请随意使用它们，但要有目的。 图片还有助于打破冗长的文本流，但它们应始终强化和反映图片之前或之后的文本。
如果您包含屏幕截图，则仅包含屏幕的相关部分，并使用标注突出显示捕获的图片与文本的相关性。
请注意不要使用包含任何信息的图表或插图——视觉或文本——这些信息可能会过时。
登录格式
大多数 Linux 发行版和 macOS 使用 log in 来描述用户如何启动交互式会话。Windows 使用 log on。
- 使用 log in 作为两个词，没有连字符，当描述一个动作（动词用法）时。
- 使用 login 作为单个词，当用作名词（罕见，但某些平台使用 login 表示用户或身份）时。
- 使用 log-in 带连字符，当修饰名词（形容词用法）时。
可选步骤
在可选步骤的开头使用 (Optional)。例如：
- 打开一个新的终端。
- 在文本编辑器中打开属性文件。
- (Optional) 添加自定义字段。
标点符号
| 元素 | 如何使用它 |
|---|---|
| 省略号 (‘) | 在缩写中使用，以获得口语化的语气。避免使用所有格形式。 |
| 大写 | 对所有标题使用句子样式的大写。在引用用户界面中的元素时，请遵循标签或文本中使用的大写。不要将常用术语大写。 |
| 冒号 (:) | 在引入过程、项目符号列表或表格的语句末尾使用冒号。 |
| 逗号 (,) | 使用串行逗号分隔一系列中的三个或更多项目，包括连词之前的项目。 |
| em 连字符 (—) | 使用 em 连字符 (—) 来设置比括号提供的强调更多的插入语短语。不要在 em 连字符周围添加空格。除非单词是专有名词，否则不要将 em 连字符后的第一个单词大写。 |
| 连字符 (-) | 避免使用带连字符的复合词。仅当没有连字符含义不明确或单词的唯一识别形式包含连字符时，才使用连字符。 |
| 引号 (" ") | 除非您需要引用消息或字符串，否则避免使用引号，否则鉴于其周围的上下文，该字符串可能会令人困惑。 |
| 分号 (;) | 不要使用分号代替逗号来分隔列表中的项目。如果您认为内容应该使用分号，请考虑将其重写为子主题或无序项目符号列表。 |
| 斜杠 (/) 和反斜杠 () | 除非记录需要正斜杠或反斜杠的路径，否则避免使用斜杠或反斜杠。在文档中永远不要使用 and/or。 |
软件版本
使用 or later 或 and later 来指代多个软件版本。例如：
- Firefox 3.6 或更高版本
- Rust 编译器 (rustc) 版本 1.55.0 及更高版本
时态
尽可能使用 现在时。 仅当您必须描述已经发生的事情时，才使用过去时。 仅当您必须描述尚未发生但可以安全假设的事情时，才使用将来时。
用户界面元素
通常，您应该避免编写有关用户界面元素的内容。相反，文档应始终关注受众 需要做什么或想要完成什么，而不是屏幕上显示的内容。
| 元素 | 如何操作 |
|---|---|
| 按钮 | 对按钮标签使用粗体。不要在描述中包含“按钮”。例如：单击 提交。 |
| 复选框 | 如果您需要在用户界面中引用复选框，请使用复选框，而不是 box 或 check box。使用 select 和 clear 以及复选框，而不是 turn on 和 turn off、mark 和 unmark、check 和 uncheck 或 unselect 和 deselect。 |
| 单击 | 使用 click 来描述对独立按钮采取操作。不要使用 click on。Click 和 select 不可互换。 |
| 对话框 | 如果您需要引用对话框，请使用 dialog。不要使用 pop-up window、dialog box 或 dialogue box。 |
| 下拉列表 | 使用 dropdown 作为形容词，而不是名词。例如，使用 dropdown list。 |
动词用法
| 动词 | 如何使用它 |
|---|---|
| allow、enable | 避免将软件作为视角，并考虑改写以关注与软件交互的人员。 |
| can、may、might | 使用动词 can 描述能力、功能或容量。避免使用动词 may，因为它暗示许可。当描述结果的可能性或偶然性时，使用过去时 might。 |
| clear | 如果您必须描述从复选框中删除选择，请使用 _clear 而不是 deselect 或 unselect。 |
| displays | 使用及物动词 displays 而不是不及物动词 appears。使用 displays 带有直接宾语。例如，该命令显示日志消息。 |
| ensure | 使用 ensure 表示确保或保证。请记住，这与 assure（使自信）和 insure（提供保险）不可互换。 |
| enter、type | 使用 enter 指示用户通过按 Enter 或 Return 键输入值。使用 type 指示用户在字段中键入值。 |
| select | 使用 select 描述对菜单项、复选框或单选按钮采取操作。请注意，click 和 select 不可互换。 |
| set up、setup | 使用 set up——两个词，没有连字符——当用作动词时。不要使用连字符。使用 setup——一个词，没有连字符——当用作形容词或名词时。 |
| want、wish | 当用户有多种操作选择时，使用 want 而不是 wish 或 desire。 |
词语选择
| 有问题的词语 | 如何使用它 |
|---|---|
| affect、effect | 使用 affect 作为动词，使用 effect 作为名词。 |
| app、application | 除非有特定原因使用缩写词 app 或 apps，否则使用 application 或 applications。 |
| back-end、front-end | 在这些术语中使用连字符仍然比不使用连字符更常见。两种形式都可以接受，但为了保持一致性，请使用连字符。 |
| 三十多年来它一直是 e-mail。永远不要使用 emails。不要将 email 用作动词。 | |
| file name | 使用 file name 作为两个词，而不是 filename。 |
| its、it’s | 使用 its 作为所有格，表示属于或与之前提到的对象或想法相关。因为它是一个模糊的代词，所以请确保可以轻松识别 it 所指代的内容。仅当 it’s 用作 it is 或 it has 的缩写时才使用它。 |
| please | 除非有特定原因使用 please，否则避免在文档中使用它。例如，如果您引用要求用户执行某些不便操作的消息的内容，则可以使用 please。 |
| prerequisite | 作为章节标题，请改用 Before you begin。如果您在文本中使用 prerequisite，则不使用连字符。 |
| that、which | 在句子的开头使用 that，该句子对于句子有意义是必要的。不要在它之前放逗号。在介绍指代人的从句时，不要使用 that。使用 who。在从句的开头使用 which，该从句为句子添加支持性或插入信息。如果您可以省略从句并且句子仍然有意义，则使用 which，并在其前面放一个逗号。 |
| user name | 使用 user name 作为两个词，而不是 username。 |
最佳实践和常见错误
本节重点介绍最佳实践和应避免的常见错误。
让每个词都发挥作用
简洁的句子更容易阅读、理解和翻译。
- 使用简单且含义明确的词语。
- 删除不增加实质内容的词语。
- 避免使用被动 to be 动词，例如 been 和 being。
- 避免使用弱或模糊的动词，例如 have、make 和 do。
如有疑问，请选择简单的词语或短语而不是更正式或更复杂的词语。例如：
| 使用此 | 不要使用此 |
|---|---|
| use | utilize、make use of |
| remove | extract、take away、eliminate |
| tell | inform、let know |
| to | in order to、as a means to |
| also | in addition |
| connect | establish connectivity |
尽可能选择具有一个明确含义的词语。 省略不必要的副词——描述如何、何时或何地的词语。除非它们对语句的含义很重要，否则请省略它们。
保持一致性
使用一个术语一致地表示一个概念。例如，如果您将 extrinsic、dispatchable 和 transaction 互换或模棱两可地使用，您将使读者感到困惑和不确定。如果术语发生变化，请准备好剔除旧术语。
如果您使用既可以是名词又可以是动词的词语——例如，诸如 file、post、mark、screen、record 和 report 等词语——请使用句子结构和上下文消除歧义。
避免悬垂分词
分词是修饰语，因此必须有名词来修饰。悬垂分词是没有名词可修饰的分词。如果您放错位置或遗漏了被修饰的词语，您将得到一个难以理解、不合逻辑或模棱两可（尽管可能很有趣）的句子。以下是一些包含悬垂分词的句子的示例：
- Looking around the yard, dandelions sprouted in every corner.
- Walking through the kitchen, the smoke alarm was going off.
- Driving like a maniac, the deer was hit and killed.
您可以通过将分词短语放在更靠近该短语打算修饰的主语的位置或更改句子的词序来澄清谁在做什么来更正这些句子。您还可以通过更改时态或使用主动语态来解决这些类型的问题。例如：
- Looking around the yard, I saw dandelions had sprouted in every corner.
- As I was walking through the kitchen, the smoke alarm was going off.
- Driving like a maniac, he hit a deer and killed it.
悬垂介词
在现代英语中，在句末使用介词完全可以接受。不要为了避免在句末使用介词而将句子扭曲得支离破碎。
- This is something you might be interested in.
- This is an example you should pay attention to.
交叉引用格式
大多数交叉引用应包含信息，以阐明读者可以预期在引用的主题中找到什么。
-
对于 Substrate 文档中主题的交叉引用，请使用以下格式：
有关 [任务或概念] 的更多信息，请参阅 [主题标题]。
-
对于术语表条目中对其他术语表条目的交叉引用，请使用以下格式：
See [topic]。
- 对于对外部资源的交叉引用，请使用目标的标题而不是目标的 URL。
避免使用指向未命名目标的链接。例如，不要使用诸如 click here 或 see this article 之类的链接。
编写概念主题
概念主题回答“为什么？”和“什么是…？”问题。 使用概念主题来：
- 解释抽象概念。
- 引入新术语。
- 提供分析。
- 提供背景信息。
概念主题的目标是帮助读者了解大局、系统或架构的关键组件以及组件之间的关系。
概念主题往往相对稳定，几乎不需要持续维护。
至少，概念主题包括至少一个标题和一个或多个正文段落。概念主题还可以包括：
- 一个或多个示例。
- 两个或多个子部分，由子标题标记。
- 相关主题列表。
构建者说明
此存储库有一些约定和特性，您在修改它（以任何方式）时需要考虑这些约定和特性。请阅读本节的全部内容，以避免常见的 gotchas 并帮助使
您的生活和维护人员的生活更轻松。
新页面和移动文件
- 如果您要添加或重命名页面，您 必须 在
src/components/DevNavMenu.tsx中正确添加它， 并且可能在gatsby-config.js和gatsby-node.js中添加它。您的index.mdx文件的title不是导航呈现的来源。
内部链接约定
- 所有
/rustdoc/内部链接必须以.html或.html#some-ID结尾。 推理可以在 #425 中找到。
通过清除 .cache 检查渲染图像
有时，开发服务器本地缓存会损坏。要在一行中修复此问题：
yarn clean && yarn dev在审查页面和每个 PR 之前，请执行此操作 - 这确保您的状态与 构建 CI 所见相同。
新的或更新的 yarn 包
有时，yarn 依赖项中会发生重大更改。要在一行中修复 main 上的此问题：
git checkout main && git pull && yarn install && yarn clean && yarn dev将上面的分支更改为您选择的工作分支，或以此方式基于
最新的 main 创建一个新的 PR。
注意：请丢弃 package.json 中添加的 "private": false, 字段。
