跳转至

Rocky Linux 文档样式指南

Rocky Linux 是世界上增长最快的企业 Linux，由于有像您这样的贡献者，其文档数量也呈指数级增长。 欢迎您以任何格式提供内容，RL 文档设计师将帮助您使其符合此处规定的标准。

序言

关于

欢迎新的贡献者将其发展为有关使用 Rocky Linux web 信息的权威站点。 您可以创建对您有意义的格式文档，文档团队将与您合作或以其他方式帮助您格式化文档，使其看起来感觉像是 Rocky 家族的一部分。

本指南概述了英语样式的标准，以 提高可读性、突出特例 并加强整个 Rocky Linux 文档的 翻译工作。 对于本指南中未涉及的样式问题，请参考以下内容：

参与贡献

要更全面地了解贡献情况，请参阅我们的相关指南：

样式指南

RL 文档旨在使用清晰和一致的语言，以便于访问，并帮助正在进行的翻译工作。

语法和标点符号

《芝加哥格式手册》中概述的 科技写作的特点 包括：

  • 双引号（"芝加哥风格"）而不是单引号（"牛津风格"）。
  • 句号和逗号要放在引号内，如 "like this,"，而不是 "like this"。
  • 破折号 {shift}+{option}+{-} 前后没有空格，如上所示，是括号短语的首选。
  • 在 "Peas, mustard, and carrots." 的列表中，在 "and" 前加一个逗号。
  • 标题通常应采用标题样式大写：第一个和最后一个单词以及所有名词、代词、动词和副词都要大写。 如果您的文档使用句子样式的大写形式效果更好，可能是因为您经常引用首字母缩写，请使其在整个文档中保持一致。
  • 标题末尾不需要句号或分号，即使使用句子样式的大写，除非以缩写结尾。
  • 有项目符号和编号的列表： 避免开头大写或结尾标点符号，除非该项目是一个完整的句子。

语态与语气

  • 简明语言。这可以被描述为一种 较少交谈对话 的样式。 我们的大部分文档都符合这一标准。
    • 避免使用比喻和成语。
    • 尽可能用最少的字表达你的意思。
    • 确定并避免不必要的专业术语。 考虑到你的受众主要是对主题有一定了解的人，但他们可能不是主题专家。
    • 简明语言的例外情况：
      • 更具对话性的风格适用于面向新手或初学者的文档，或用于撰写博客文章等内容。
      • 更正式或更简洁的措辞风格适用于面向高级用户的文档或 API（Application Programming Interface) 文档。
  • 包容性语言。
    • 语言的使用会随着时间的推移而演变。 某些词语已经演变为具有负面含义，因此应重新编写文件，使用新词。
      • Master/slave 就变成了 primary/secondary 或约定俗成的组织标准。
      • Blacklist/whitelist 变成了 blocklist/allowlist 或约定俗成的组织标准。
      • 在创建文档时，您可能会想到其他相关的示例。
    • 当谈到 unknown 或 non-binary 性别的人时，现在认为可以将 "They" 用作单数代词。
    • 当谈到一个能力时，把答案框定为 abilities 而不是 limitations。例如，如果您想知道我们是否有关于在 Rocky Linux 上运行 Steam 的文档，答案不仅仅是 "no"。 而是说："听起来那是一个好地方，您可以创建一些东西来添加到我们的文档树中！"
  • 避免缩约形式 以助于翻译工作。 例外情况——在撰写博客文章或社区新成员欢迎说明等对话性较强的文章时。

格式

日期

如果可能，请使用格式为 {day} {Month} {year} 的月份名称。 不过，为了解决清晰或外观问题， {Month} {day}, {year} 也是可以接受的。 无论哪种方式，为了避免混淆，请写出月份名称而不是一系列数字。 例如：24 January 2023, but January 24, 2023 is also acceptable—with both preferable over 1/24/2023 or 24/01/2023.

单步骤程序

如果您的过程只有一个步骤，请使用项目符号而不是数字。 例如：

  • 落实这一想法，然后继续前进。

图形界面语言

  • 关于 UI 的文本说明：当描述要输入到用户界面中的命令时，请使用单词 "enter"，而不是 "put" 或 "type"。 使用代码块写出命令（即用反引号将其设置）：

示例 Markdown 文本 在 **提交消息** 框中，输入 update_thisdoc。

  • UI 元素的名称：UI元素（如按钮、菜单项、对话框名称等）的 粗体 名称，即使单词不可单击：

示例 Markdown 文本 在 **Format** 菜单中，点击 **Line Spacing** 。

结构

每本指南的开头内容，或一本书的页面/章节

  • Abstract. 简要说明本页的预期内容
  • Objectives. 本页将向读者传达的内容列表
  • Skills 需要或学习什么。
  • Difficulty level. 1星表示简单、2星表示中级等等。
  • Reading time. 将文件中的单词数除以每分钟 75 个单词的阅读速度，即可得出这一数字。

Admonitions

在 Markdown 中，admonitions 是将信息放入框中以突出显示的一种方法。 它们对文档不是必不可少的，但可能是一种有用的工具。 从我们的 Rocky Formatting 文档中了解有关 admonitions 的更多信息。

无障碍环境

以下标准提高了使用屏幕阅读器等辅助工具的用户访问我们文档的无障碍性。

图片

  • 为每个非文本项目（如图表、图像或图标）提供替换文本或标题的文本描述。
  • 尽可能避免文本截屏。
  • 让替代文本有意义，而不仅仅是描述性的。 例如，对于操作图标，请输入功能描述而不是外观描述。

链接

  • 使链接具有描述性，这样就可以清楚地从文本或上下文中看到它们的指向。 避免使用名称类似 "click here" 的超链接。
  • 验证所有链接都能按描述正常工作。

表格

  • 按照从左到右、从上到下的逻辑顺序创建表格。
  • 避免在表格顶部或左侧出现空白单元格。
  • 避免合并跨多列的单元格。

颜色

  • Markdown 中的一些元素，如 admonitions，它有指定的颜色来帮助视觉理解。 例如，"danger" admonition 会显示一个红框，但同时也有 "danger" 的描述。 但在创建自定义 admonition 时，请注意颜色不能作为传达命令或警告级别的唯一手段。
  • 任何包含感官指示（如 above 或 below、color、size、在页面上的 visual location 等）的指令，也应包含仅通过文字描述即可传达的指示。
  • 在创建图形元素时，确保前景色和背景色之间有足够的对比度，以便屏幕阅读器轻松解读。

标题

  • 使用所有级别的标题，不要跳过任何级别。
  • 将所有资料放在标题下，以帮助阅读。
  • 请记住，在 Markdown 中，只能使用一个一级标题。

总结

本文档列出了我们的贡献标准，包括 样式指南、如何 构建 文件以及如何将 包容性 和 无障碍性 纳入文本。 这些是我们渴望达到的标准。 在创建和修改文档时，请尽可能牢记这些标准。

但是 —请不要忽略这一点— 请将这些标准视为一种工具，而不是障碍。本着包容性和无障碍性的精神，我们希望确保您的贡献能顺利进入到 Rocky 家族。 我们是一个友好、乐于助人的纪录片制作团队，我们将帮助您将文件制作成最终版本。

您准备好了吗？ 让我们开始吧！

Author: Ezequiel Bruni, Krista Burdine

Contributors: Steven Spencer, Ganna Zhyrnova