跳至内容

Rocky Linux 文档风格指南

Rocky Linux (RL) 是增长最快的企业级 Linux 发行版，得益于像您一样的贡献者，其文档也在呈指数级增长。您的内容以任何格式都受到欢迎，RL 的文档样式专家将帮助您将其与此处设定的标准对齐。

简介

关于

欢迎新的贡献，以将此指南打造成关于使用 Rocky Linux 的信息的网络权威之地。您可以以您认为最合适的方式创建文档，文档团队将与您合作或以其他方式帮助您进行格式化，使其看起来和感觉上都像是 Rocky 大家庭的一部分。

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

贡献

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

风格指南

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

语法和标点

芝加哥写作风格手册中概述的**技术写作的特点**包括以下几点：

  • 使用双引号（“芝加哥风格”）而不是单引号（‘牛津风格’）。
  • 句号和逗号放在引号内，“像这样”，而不是“像这样”。
  • 破折号 {shift}+{option}+{-} 前后没有空格——像这样—，我们偏好用它来表示插入语。
  • 在三个项目的列表中，在“和”之前使用序列逗号：“豌豆、芥末和胡萝卜。”
  • 标题通常应使用句子首字母大写：仅首字母和专有名词大写。使整个文档的标题格式保持一致。
  • 标题末尾不需要句号或分号，即使使用句子首字母大写，除非以缩写结尾。
  • 项目符号列表和编号列表：避免首字母大写或结尾标点，除非该项是完整的句子。

句子式标题大写

文档中的当前标准是使用句子式大写。使用 vale 和其他语言检查器的人会发现它们建议使用句子式大写。我们文档库中创建的大部分文档都使用了这种标题大写风格。这与芝加哥写作风格手册不同，但由于行业已转向文档标题的这种风格，因此本文件修改为包含此建议。

语气和语调

  • 简洁明了的语言。被描述为一种不太口语化的风格。我们的大部分文档都符合此标准。
    • 避免使用隐喻和习语。
    • 用尽可能少的词语表达您的意思。
    • 识别并避免不必要的术语。请考虑到您的读者大多对主题有所了解，但可能不是该领域的专家。
    • 简洁明了语言的例外情况
      • 对于面向新用户或初学者的文档，或者在撰写博客文章等内容时，更口语化的风格是合适的。
      • 对于面向高级用户或 API（应用程序编程接口）文档的写作，更正式或简洁的措辞风格是合适的。
  • 包容性语言。
    • 语言使用会随着时间推移而演变。某些词语会演变成带有负面含义，因此文档应重写以使用新的词语。
      • 主/从变为主要/次要或双方同意的组织标准。
      • 黑名单/白名单变为阻止名单/允许名单或双方同意的组织标准。
      • 在创建文档时，您可能会想到其他相关的例子。
    • 在谈论性别未知或非二元的人时，现在可以使用“他们”作为单数代词，这是可以接受的。
    • 在谈论某人的能力时，将回答表述为能力而不是限制。例如，如果您想知道我们是否有关于在 Rocky Linux 上运行 Steam 的文档，答案不仅仅是“没有”。而是，“听起来那是个很棒的地方，您可以创作一些内容添加到我们的资源库中！”
  • 避免使用缩写。这有助于翻译工作。例外情况是，在撰写更口语化的内容时，例如博客文章或新社区成员的欢迎指南。
  • 使用主动语态。主动语态更清晰、更直接，有助于读者快速理解您的意思。

其他关于语气和语调的阅读材料

自本风格指南创建以来，已创建了多份关于语气和语调的附加文档，包括：
- 好的文档——译者的视角
- 主动语态——简单、清晰的沟通之道

格式

日期

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

单步操作

如果您的操作只有一步，请使用项目符号而不是编号。例如：

  • 实施这个想法，然后继续。

图形界面语言

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

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

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

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

结构

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

  • 摘要。简要说明本页面内容。
  • 目标。列出本页面将向读者传达的内容。
  • 所需/学到的**技能**。
  • 难度级别。1 星表示简单，2 星表示中等，以此类推。
  • 阅读时间。将文档中的字数除以每分钟 75 字的阅读速度来确定此数字。

提醒

在 Markdown 中，通知是一种将信息放入框中以突出显示的方式。它们对文档并非必需，但它们是您可能会发现有用的工具。请参阅我们的Rocky 格式文档，了解更多关于通知的信息。

可访问性

以下标准可增强使用屏幕阅读器等辅助功能访问我们文档的用户体验。

图片

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

表格

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

颜色

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

标题

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

总结

本文档概述了我们的贡献标准，包括**风格指南**、如何**构建**您的文档，以及如何将**包容性**和**可访问性**融入文本。这些是我们努力追求的标准。在您有能力的情况下，在创建和修改文档时请牢记这些标准。

但是——请注意这一点——**将这些标准视为工具，而不是障碍。**本着包容性和可访问性的精神，我们希望确保您的贡献能够顺利融入 Rocky 的家族体系。我们是一支友好且乐于助人的文档撰写者和样式专家团队，我们将帮助引导您的文档形成最终形式。

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

作者：Ezequiel Bruni, Krista Burdine

贡献者：Steven Spencer, Ganna Zhyrnova