参与 Timescale 文档贡献

Timescale 文档托管在 GitHub 仓库中，并向所有社区成员开放贡献。如果您发现错误或想向我们的文档添加内容，您可以创建拉取请求，通过 GitHub 提交以供我们的文档团队审核。本文档包含您需要了解的关于我们写作风格和标准的所有信息，但如果您不确定写什么，请不要过于担心。当您准备好 PR 时，我们的文档团队会帮助您撰写完美的措辞。我们还在我们的仓库中提供了一些自动化工具来帮助您。

如果您想对文档进行小的更改，例如修复拼写错误，您可以在 GitHub 网站上进行更正并提交拉取请求。转到您要更正的文件，然后单击“铅笔”图标进行编辑。进行更正，并使用页面底部的选项提交拉取请求。

要对文档进行较大的更改，请按照我们的贡献者指南中的说明进行操作。

有关仓库的技术细节，包括了解仓库的组织方式以及各种标记和格式约定，请参阅 README。

在我们接受任何贡献之前，Timescale 贡献者需要签署贡献者许可协议 (CLA)。通过签署 CLA，我们可以确保社区可以自由且自信地使用您的贡献。在拉取请求过程中，系统会提示您签署 CLA。

在进行风格决策时，请按此顺序查阅资源

1. 本指南：始终首先查看本指南，它包含项目特定的指导，并且在某些情况下与此处列出的其他资源不同。
2. Google 开发者文档风格指南：对于大多数通用风格指导，我们依赖于此处定义的风格。
3. 《芝加哥格式手册》：我们使用本指南来处理其他资源未涵盖的某些格式决策
4. 韦氏词典：Timescale 文档以美式英语书写，对于拼写和定义，请查阅词典。

我们使用标准美式英语，重点是使用简单（或经典）语言，使用一般现在时，使用第二人称单数（“您”）。我们偏爱主动语态，但如果被动语态能达到目的，也不要害怕使用。始终选择最简单和最清晰的语言，无论它是主动语态还是被动语态。

例如，以下是编写一个句子的三种方式

• 自然英语：为了执行 X 安装过程，请确保完成以下所有步骤...
• 技术写作者英语：要执行 X 安装过程，请验证您已完成后续步骤...
• 简明英语：要安装 X，请执行以下步骤...

请记住，单词的顺序在英语中很重要。将句子中最重要的部分放在最前面，这通常是执行者或动作。使用句子的第二部分来突出重点：读者还应该注意什么？

当读者阅读我们的文档时，他们通常处于焦虑状态。压力大的读者会在文本中跳跃，跳过单词、步骤或段落，如果事情看起来太复杂，他们可能会很快放弃。为了缓解这种情况，请使用简短的句子、简明的语言以及最少数量的引人注目的细节，例如告诫。

永远不要认为因为您在文档的前面解释了某些内容，读者在文档的后面就知道。您可以使用交叉引用来帮助引导读者获取更多信息（如果他们需要）。

语法规则是默认的演变约定。它们本身没有内在价值，它们获得价值仅仅是因为每个人都在这样做。

对于悬垂分词、分裂不定式或以介词结尾的句子，没有硬性规定。遵守这些规则通常可以使语言更清晰，但在某些情况下，它们会使语言更复杂。在那种情况下，请随意忽略它们。

所有标题都应以句子形式书写：仅将标题中的第一个单词和专有名词大写。

对于顶级页面标题和大多数章节标题，请使用最简单的名词短语。例如，不要使用“使用超表”，而是将页面称为“超表”。

对于包含一个或多个过程的二级章节，请使用简单的动词短语。例如，“安装 Timescale”。对于相关的过程，请使用三级标题，并使用相同标题的动名词形式。例如，“安装 Timescale”。

您可以使用项目符号列表或编号列表来呈现信息。如果您不确定是使用项目符号还是编号，请应用测试，“顺序重要吗？” 如果顺序很重要，请使用编号。如果列表项可以按任何顺序阅读，请使用项目符号。

始终以大写字母开头每个列表项。如果列表项是简短的、不完整的句子，请不要在每个项目末尾添加标点符号。但是，如果任何列表项是包含多个完整句子的较长短语，请在所有列表项末尾加上句点。

1.   Use numbers
1.   If the order of the steps
1.   Is important

*   Otherwise
*   Use
*   Bullets

复制

我们使用流程和程序为读者提供编号的步骤，以实现特定目标。

流程包含程序。如果您描述的任务非常冗长，或者具有一系列不同的组件，请将其分解为流程内的一系列程序。

程序包含以下元素

1. 二级章节标题，使用简单的动词形式
2. 简短介绍
3. 打开 <Procedure> 标签
4. 三级程序标题，使用动名词动词形式
5. 编号步骤
6. 屏幕截图
7. 关闭 </Procedure> 标签

例如

## Install Timescale

This section describes how to install Timescale on premise.

<Procedure>

### Installing Timescale

1. Start each step with a verb, or a location.
1. For example, "Run the `example` command", or "At the command prompt, open the
   `example` file."

<Add screenshot here>

</Procedure>

复制

通常，不要使用结果陈述。但是，如果您觉得绝对必要，请将其放在结束程序标签之前，并且不要将其作为步骤。

通过使用三个反引号并将块中使用的语言声明为代码块偏移周围的文本。通常，查询使用 sql，命令行提示符给出的命令使用 bash。有关可用语言的完整列表，请参阅 prismjs 站点。

确保代码块的缩进级别与周围文本的级别相同。

在代码块中编写命令时，请勿使用 #、$ 或任何其他提示符。此外，对于 Linux 命令，请勿使用 sudo，而是使用词干句子来指示该命令必须以 root 用户身份运行。

例如，bash 命令

At the command prompt, as root, use this command:

    ```bash
    apt install postgresql
    ```

复制

例如，SQL 查询

At the `psql` prompt, use this query:

    ```sql
    SELECT * FROM table LIMIT 5;
    ```

复制

• 使用鼠标单击图形用户界面中的按钮。不要单击在。
• 按键盘上的键或组合键。
• 使用键盘键入单词或数字。
• 选中或取消选中复选框。
• 选择或取消选择菜单中的项目。
• 导航到图形用户界面中的页面或位置。

Above（上方）：避免所有方向词。您无法保证事物会保持在相同的位置，或者位于您在个别读者设备上期望的位置。

Adverbs（副词）：不要使用。

❌ Simply install Timescale.（只需安装 Timescale。）

👍 Install Timescale.（安装 Timescale。）

AWS：Amazon Web Services（亚马逊网络服务）。无需展开此首字母缩略词。

And/Or（和/或）：不要使用。您通常可以选择一个。如果您不确定，请选择“and”（和）。

❌ I like apples and/or oranges.（我喜欢苹果和/或橙子。）

👍 I like apples and oranges.（我喜欢苹果和橙子。）

Appears（出现）：不要使用。

Bare metal（裸机）：名词。

❌ "Perform a bare metal installation."（执行裸机安装。）

👍 "Install Timescale on bare metal."（在裸机上安装 Timescale。）

Bare-metal（裸机的）：形容词。

❌ "Install Timescale on bare-metal."（在裸机上安装 Timescale。）

👍 "Perform a bare-metal installation."（执行裸机安装。）

Backend（后端）：一个词。

Below（下方）：避免所有方向词。您无法保证事物会保持在相同的位置，或者位于您在个别读者设备上期望的位置。

Contractions（缩略形式）：绝对可以使用，但尽量不要过度使用。

Cybersecurity（网络安全）：一个词。

Dataset（数据集）：一个词。

❌ "Ingest the example data set."（摄取示例数据集。）

👍 "Ingest the example dataset."（摄取示例数据集。）

Fail over（故障转移）：用作动词

Failover（故障转移）：用作名词或形容词。

File system（文件系统）：两个词。

Frontend（前端）：一个词。

GCP：Google Cloud Platform（谷歌云平台）。无需展开此首字母缩略词。

Hypershift：一个词，始终大写。发布前仔细检查此单词的拼写。

Latin abbreviations（拉丁文缩写）：不要使用。

❌ eg

👍 For example（例如）

❌ I.E

👍 That is,（即，）

Log in（登录）：动词。

❌ "Enter your log in information."（输入您的登录信息。）

👍 "Log in to Timescale."（登录到 Timescale。）

Login（登录）：形容词或名词。

❌ "Login to Timescale."（登录到 Timescale。）

👍 "Enter your login information."（输入您的登录信息。）

Managed Service for TimescaleDB（TimescaleDB 托管服务）：产品的名称。始终将首字母大写。不要缩写。

❌ "I am using Managed Service for Timescale to manage my time-series data."（我正在使用 Timescale 托管服务来管理我的时序数据。）

❌ "I am using Managed Service to manage my time-series data."（我正在使用托管服务来管理我的时序数据。）

👍 "I am using Managed Service for TimescaleDB to manage my time-series data."（我正在使用 TimescaleDB 托管服务来管理我的时序数据。）

Master/Slave（主/从）：不要使用。请改用“Primary”（主）和“Secondary”（从）。

MST：不要使用。请改用“Managed Service for TimescaleDB”（TimescaleDB 托管服务）。

Next（下一个）：避免所有方向词。您无法保证事物会保持在相同的位置，或者位于您在个别读者设备上期望的位置。

Once（一旦）：不要使用。请改用“when”（当）。

❌ "Once you have finished the installation, you can..."（一旦您完成安装，您就可以...）

👍 "When you have finished the installation, you can."（当您完成安装后，您可以。）

Postgres：不要使用。请改用“PostgreSQL”。

❌ "Run the Postgres query"（运行 Postgres 查询）

👍 "Run the PostgreSQL query."（运行 PostgreSQL 查询。）

PostgreSQL：始终使用全名并使用正确的 capitalization（大写），如所示引用 PostgreSQL。

Previous（上一个）：避免所有方向词。您无法保证事物会保持在相同的位置，或者位于您在个别读者设备上期望的位置。

Simply（简单地）：不要使用。

❌ Simply install Timescale.（只需安装 Timescale。）

👍 Install Timescale.（安装 Timescale。）

Superuser（超级用户）：一个词。

Thus（因此）：不要使用。

Timescale：公司名称，以及广义上产品的名称。不要使用驼峰式大小写。

❌ TimeScale

👍 Timescale is hosting a virtual event.（Timescale 正在举办虚拟活动。）

👍 I have installed Timescale to manage my time-series data.（我已经安装 Timescale 来管理我的时序数据。）

Timescale：产品的名称。始终将首字母大写。

❌ "I am using timescale to manage my time-series data."（我正在使用 timescale 来管理我的时序数据。）

❌ "I am using Timescale Cloud to manage my time-series data."（我正在使用 Timescale Cloud 来管理我的时序数据。）

👍 "I am using Timescale to manage my time-series data."（我正在使用 Timescale 来管理我的时序数据。）

TimescaleDB：PostgreSQL 扩展的名称。如果在散文中引用，始终将首字母和末尾的 DB 大写。如果直接引用扩展的名称，请使用全部小写。

❌ "I installed timescaleDB to manage my time-series data."（我安装了 timescaleDB 来管理我的时序数据。）

👍 "I installed the timescaledb extension to manage my time-series data."（我安装了 timescaledb 扩展来管理我的时序数据。）

👍 "I installed TimescaleDB to manage my time-series data."（我安装了 TimescaleDB 来管理我的时序数据。）

tobs：可观测性套件。不要使用大写，即使它在句子开头也是如此。如果可能，请重写句子以避免这种情况。

❌ "Tobs can be used to install."（Tobs 可以用于安装。）

👍 "Install using tobs"（使用 tobs 安装）

TSDB：不要使用。请改用“Timescale database”（Timescale 数据库）。

Update（更新）：更新是小的或次要的改进，通常在补丁中交付。更新频繁进行，几乎不需要停机。

👍 Install the security update to patch this version.（安装安全更新以修补此版本。）

Upgrade（升级）：升级是大的或主要的改进，通常需要新版本。升级不太频繁地进行，可能需要计划、准备备份和计划停机。

👍 Upgrade from TimescaleDB 1 to TimescaleDB 2.（从 TimescaleDB 1 升级到 TimescaleDB 2。）

👍 Upgrade from TimescaleDB 2.3 to TimescaleDB 2.4.（从 TimescaleDB 2.3 升级到 TimescaleDB 2.4。）

Utilize（利用）：不要使用。请改用“use”（使用）。

Vanilla PostgreSQL（纯 PostgreSQL）：不要使用。如果您想区分常规 PostgreSQL 表和包含时序的表，请使用“standard PostgreSQL”（标准 PostgreSQL）。

❌ "You can also create services that run vanilla PostgreSQL."（您还可以创建运行纯 PostgreSQL 的服务。）

👍 "You can also create services that run standard PostgreSQL."（您还可以创建运行标准 PostgreSQL 的服务。）

Via（通过）：不要使用。通常有更准确的英语单词，例如“through”（通过）、“with”（使用）或“using”（使用）。

Will（将）：不要使用。它通常表示您正在使用将来时态写作。始终使用一般现在时写作。

❌ After installation, you will see a message.（安装后，您将看到一条消息。）

👍 After installation, you see a message.（安装后，您会看到一条消息。）