自制文档

散文风格指南

这是一套针对自制散文文档的风格和用法指南，面向用户、贡献者和维护者（与可执行计算机代码相对）。它适用于Homebrew/brew 存储库中的docs 中的文档、公告电子邮件以及与自制社区的其他通信。

这并不适用于任何 Ruby 或其他计算机代码。你可以使用它来了解从计算机代码中提取的技术文档，例如嵌入式手册页，但它只是一个建议。

目标和受众

自制散文文档的主要目标是与用户和贡献者社区进行沟通。“用户”在此处包括“贡献者”；无论你在哪里看到“用户”，都可以用“用户和贡献者”代替。

可理解性比任何特定风格指南都更重要。

用户优先于维护者，特别是在以维护者为重点的文档中除外。

自制的受众包括受教育程度和经验范围很广的用户，以及英语不是母语的用户。我们的目标是尽可能支持这些用户。

我们努力做到“正确”而不是“花哨”的使用。想想报纸文章，而不是学术论文。

这是一套使用人类判断力应用的指南，而不是一套严格的规则。它就像经济学人风格指南或加纳的现代美国用法。它不像Ruby 风格指南。这里的指南都可以解释和讨论。100% 符合这些指南不是目标。

本文档的目的是帮助作者做出有关清晰度、风格和一致性的决策。它不是为了帮助解决谁更了解英语的争论。不要使用本文档来当混蛋。

指南

我们更喜欢

风格和用法

• 一般来说，英式/联邦英语优于美式英语
• “e.g.” 和 “i.e.”：继续使用 “e.g.” 或 “i.e.”，而不是拼写它们。不必担心在它们后面加逗号。
  • “e.g.” 表示“例如”；“i.e.” 表示“即”
• 用逗号隔开非平凡的从属从句

人称代词

• 我们尊重所有人选择人称代词的权利
• 当某人的性别未知时，使用单数“they”
• 在没有必要时，避免使用性别特定的语言

结构和标记

• 在 h1 标题中使用标题大小写；在所有其他标题中使用句子大小写
• 在列表项的末尾加句号，其中该列表中的大多数项都是完整句子
• 更一般地说，并行列表项结构
• 如果你愿意，可以对所有列表项进行大写，即使它们不是完整句子；只要在每个列表中保持一致，最好在整个页面中保持一致
• 使用从属列表项，而不是将一个多句段的段落项放入句子片段列表中
• 除非需要 Markdown 的特定功能，否则优先使用 Markdown 而非其他标记格式
  • GitHub 风味 Markdown。GitHub 的实现是标准，句号。

印刷惯例

• 命令和代码中的文字以 固定宽度字体 样式显示
• 代码片段中的占位符用 <...> 括号标记
  • 例如 git remote add <my-user-name> https://github.com/<my-user-name>/homebrew-core.git
• 像 git 和 brew 这样的命令名称以 固定宽度字体 样式显示
• 在代码片段之外提到的环境变量中没有“$”
  • 例如，“将 BLAH 设置为 5”，而不是“将 $BLAH 设置为 5”
• 句号后留一个空格，而不是两个
• 大写专有名词
• 除了专有名词的正常大写和简单的内部大写之外，我们不会推迟广泛的非标准大写、排版或其他品牌名称样式
• 没有“TM”、“™”、“^SM”、“©”、“®”或其他明确的权利所有权或商标指示符；当提到品牌名称时，我们认为这些是理所当然的
• 像 homebrew/core 这样的水龙头名称以 固定宽度字体 样式显示。存储库名称可以用固定宽度字体显示，如“Homebrew/homebrew-core”，作为链接显示，如“Homebrew/homebrew-core”，或常规文本，如“Homebrew/homebrew-core”，具体取决于哪种方式最适合给定的用途。
  • 但在单个文档中保持一致
  • 将存储库名称大写，以匹配 GitHub 上的用户和存储库名称。保持水龙头名称小写。
• 逗号
  • 没有牛津逗号
  • 优先使用“松散”逗号样式：“如有疑问，就不要使用”，除非为了清晰度需要

术语、单词和单词样式

• “pull request”，而不是“Pull Request”
• “check out”是动词；“checkout”是名词
• 拼写出某些技术术语
  • “repository”，而不是“repo”
  • 缩写时，在任何文档中首次使用时引入缩写
• 不过，一些缩写（在我们的用户群中几乎普遍理解）是可以的。
  • “Mac”是可以的；“Macintosh”没有必要
• 所有版本的“macOS”；描述特定旧版本时为“OS X”或“Mac OS X”
• “RuboCop”，而不是“Rubocop”
• 拉取请求是在存储库“上”进行的；该存储库在 URL“中”

如何使用这些准则

参考这些准则，以便在为 Homebrew 文档和通信撰写自己的文章时对风格和用法做出决策。

修复整个文档或多个文档中的风格和用法的 PR 是可以的，并且是鼓励的。仅针对一两个风格更改的 PR 有点过分。

对涉及文档的 PR 或提交提供风格和用法反馈是可以的，并且是鼓励的。但请记住，这些只是准则，对于任何更改，作者可能出于可理解性或美观的目的而故意选择打破这些规则。