跳过内容

Rocky Linux 文档风格指南

Rocky Linux 是全球增长最快的企业 Linux，其文档也随着像您这样的贡献者的努力而呈指数级增长。您的内容以任何格式都受欢迎，RL 文档造型师将帮助您将其与此处列出的标准保持一致。

简介

关于

欢迎新的贡献，将此发展成为网络上有关使用 Rocky Linux 信息的权威资料来源。您可以以对您有意义的格式创建文档，文档团队将与您合作或以其他方式帮助您格式化它，使其看起来和感觉起来像 Rocky 家族的一部分。

本指南概述了英语风格标准，以**提高可读性，突出特殊情况**和**增强 Rocky Linux 文档的翻译工作**。对于本指南中未涉及的风格问题，请参考以下内容

贡献

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

风格指南

RL 文档旨在使用清晰一致的语言，以实现可访问性以及帮助进行持续的翻译工作。

语法和标点

**技术写作的特色**如芝加哥格式手册中所述，包括以下内容

  • 双引号（“芝加哥风格”）而不是单引号（‘牛津风格’）。
  • 句号和逗号放在引号内“像这样”，而不是“像这样”。
  • em 破折号 {shift}+{option}+{-} 在前后没有空格—像这样—，它更适合用于插入语。
  • 在三个项目列表中的“and”之前使用系列逗号：“豌豆、芥末和胡萝卜”。
  • 标题通常应使用标题风格的大写：大写第一个和最后一个词，以及所有名词、代词、动词和副词。如果您的文档在句子风格的大写中效果更好，可能是因为您经常引用首字母缩略词，请在整个文档中保持一致。
  • 标题末尾不需要句号或分号，即使是句子风格的大写也是如此，除非以缩写结尾。
  • 项目符号和编号列表：除非该项目是一个完整的句子，否则避免开头大写或结尾标点符号。

语气和语调

  • **普通语言。**这可以被描述为一种不太口语化的风格。我们的大部分文档都符合此标准。
    • 避免使用比喻和习语。
    • 尽可能用最少的词语表达你的意思。
    • 识别并避免使用不必要的技术术语。请考虑您的受众主要是对主题有一定了解的人，但可能不是主题专家。
    • 普通语言的例外
      • 对于针对新手或初学者的文档，或编写博客文章等内容，更口语化的风格是合适的。
      • 对于针对高级用户或 API（应用程序编程接口）文档的文档，更正式或简洁的措辞风格是合适的。
  • 包容性语言。
    • 语言随着时间的推移而发展。某些词语已经发展出负面含义，因此应重写文档以使用新词语。
      • 主/从 变成 主/辅 或一个商定的组织标准。
      • 黑名单/白名单 变成 阻止列表/允许列表 或一个商定的组织标准。
      • 在创建文档时，您可能会想到其他相关的示例。
    • 当谈论未知或非二元性别的个人时，现在使用“they”作为单数代词被认为是可以接受的。
    • 当谈论一个人的能力时，将答案表述为能力而不是局限性。例如，如果您想知道我们是否有关于在 Rocky Linux 上运行 Steam 的文档，答案不仅仅是“没有”。相反，“听起来这对你来说是一个很棒的地方，你可以创建一些内容添加到我们的树中！”
  • 避免使用缩写。 这有助于翻译工作。 唯一的例外是在写一些更口语化的内容时，例如博客文章或新社区成员的欢迎指南。

格式

日期

如果可能，请使用 {day} {Month} {year} 格式的月份名称。 但是，{Month} {day}, {year} 也是可以接受的，以解决清晰度或外观问题。 无论哪种方式，为了避免混淆，请写出月份名称，而不是一系列数字。 例如：2023 年 1 月 24 日，但 2023 年 1 月 24 日也是可以接受的——两者都优于 1/24/2023 或 24/01/2023。

单步流程

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

  • 实施这个想法并继续。

图形界面语言

  • 关于 UI 的文本说明：描述要输入用户界面的命令时，请使用“输入”而不是“放”或“键入”。 使用代码块写出命令（即，用反引号将其隔开）

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

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

示例 Markdown 文本 在 **格式** 菜单中，单击 **行距**。

结构

每个指南或书籍页面/章节的起始内容

  • 摘要。 简要说明本页的内容
  • 目标。 本页将传达给读者的项目符号列表
  • 所需/学习的技能。
  • 难度级别。 1 星级代表简单，2 星级代表中等，等等。
  • 阅读时间。 将文档中的字数除以每分钟 75 个字的阅读速度来确定这个数字。

警示

在 Markdown 中，警示是一种将信息放入框中以突出显示它们的方法。 它们对于文档来说不是必需的，但它们是一个你可能会发现有用的工具。 从我们的 Rocky 格式化文档 中了解更多关于警示的信息。

可访问性

以下标准提高了使用辅助工具（如屏幕阅读器）访问我们文档的人的可访问性。

图像

  • 为每个非文本项目（如图表、图像或图标）提供 alt-text 或标题中的文本描述。
  • 如果可能，请避免使用文本的屏幕截图。
  • 使 alt-text 有意义，而不仅仅是描述性。 例如，对于操作图标，输入函数的描述，而不是其外观的描述。
  • 使链接描述性，以便从文本或上下文中清楚地知道它们将通向何处。 避免使用诸如“点击这里”之类的名称的超链接。
  • 验证所有链接是否按描述工作。

表格

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

颜色

  • Markdown 中的一些元素，例如警示，都有分配的颜色以帮助视觉理解。 通常它们也都有一个分配的名称； 例如，“危险”警示显示一个红色框，但它还在描述中内置了“危险”描述符。 但是，在创建自定义警示时，请注意，颜色不能成为传达命令或警告级别的唯一手段。
  • 任何包含感官方向的命令，例如上方或下方、颜色、大小、页面上的视觉位置等，也应该包含一个仅通过文本描述即可传达的方向。
  • 在创建图形元素时，确保前景和背景颜色之间有足够的对比度，以便屏幕阅读器能够轻松地解释。

标题

  • 使用所有级别的标题，不要跳过任何级别。
  • 将所有材料嵌套在标题下以帮助提高可读性。
  • 请记住，在 Markdown 中，只能使用一个一级标题。

摘要

本文档概述了我们的贡献标准，包括样式指南、如何构建您的文档以及如何在文本中融入包容性和可访问性。 这些是我们追求的标准。 只要您能够做到，在创建和修改文档时请牢记这些标准。

但是——不要错过这个警告——将这些标准视为一种工具，而不是障碍。本着包容性和可访问性的精神，我们希望确保您的贡献能够顺利进入 Rocky 家族树。 我们是一支友好而乐于助人的文档编制和样式专家团队，我们将帮助您将您的文档引导到最终形式。

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

作者：Ezequiel Bruni、Krista Burdine

贡献者：Steven Spencer、Ganna Zhyrnova