如何参与编辑 SQL Server 文档

  • 项目

适用于：SQL ServerAzure SQL 数据库Azure Synapse AnalyticsAnalytics Platform System (PDW)

任何人都可以参与编辑 SQL Server 文档。 这包括更正拼写错误、提出更好的解释以及改进技术的准确性。 本文介绍如何开始参与内容编辑以及此过程的工作原理。

可通过以下两个主要工作流参与编辑：

工作流 说明
在浏览器中编辑 适用于对任何文章进行少量快速编辑。
使用工具在本地编辑 适用于更复杂的编辑、涉及多篇文章的编辑，以及频繁参与。

SQL 内容团队会对所有公开发表的内容进行验证，以确保技术准确性和一致性。

在浏览器中编辑

可以在浏览器中对 SQL Server 内容进行简单编辑，然后将其提交到 Microsoft。 有关详细信息，请参阅参与者指南概述。

以下步骤概述了这一过程：

  1. 在要进行反馈的页面上，选择右上角的“铅笔”图标。
  2. 在下一页中，选择右上角的铅笔图标。 如果未显示此图标，则可能需要先登录到 GitHub 帐户。
  3. 在下一页上的“编辑文件”文本窗口中，对要更改的文本直接进行编辑。 如果需要有关对新文本或更改的文本设置格式的帮助，请参阅 Markdown 速查表。
  4. 进行编辑之后，请在“提交更改”下：
    1. 在第一个文本框中，输入所进行的更改的简要说明。
    2. 在“添加一个可选的扩展说明”框中，提供对更改的简短解释。
  5. 选择“建议文件更改”。
  6. 在“比较更改”页面上，选择“创建拉取请求”。
  7. 在“打开拉取请求”页面上，选择“创建拉取请求”。

下面的 GIF 演示了在浏览器中提交更改的完整过程：

Screenshot of Edit SQL Docs.

使用工具在本地编辑

另一个编辑选项是创建 sql-docs 或 azure-docs 存储库的分支并将其克隆到本地计算机。 然后可以使用 Markdown 编辑器和 git 客户端提交所做的更改。 此工作流适用于更复杂或涉及多个文件的编辑。 它也适用于 Microsoft 技术文档的频繁参与者。

若要使用此方法参与编辑，请参阅以下文章：

如果提交包含对文档的重大更改的拉取请求，则在 GitHub 中收到一条注释，要求提交联机“贡献许可协议 (CLA)”。 必须先完成联机窗体，然后系统才会接受你的拉取请求。

识别

如果接受了你所做的更改，则系统会在文章顶部将你识别为参与者。

Screenshot of Content contribution recognition.

SQL-docs 概述

本部分提供有关在 sql-docs 存储库中工作的其他指导。

重要

本部分中的信息特定于 sql-docs。 如果要编辑 Azure 文档中的 SQL 文章，请参阅 GitHub 上 azure-docs 存储库的自述文件。

sql-docs 存储库使用多个标准文件夹来组织内容。

Folder 说明
docs 包含所有已发布的 SQL Server 内容。 子文件夹有逻辑地组织内容的不同区域。
docs/includes 包括包含文件。 这些文件是可以包含在一个或多个其他文章中的内容块。
./media 每个文件夹可以有一个用于文章图像的“media”子文件夹。 “media”文件夹又包含名称与图像出现的文章名称相同的子文件夹。 图像应为字母全部小写且没有空格的 .png 文件。
TOC.MD 目录文件。 每个子文件夹都可选择使用 TOC.MD 文件。

“适用范围”包含

每篇 SQL Server 文章的标题后都包含“applies-to”包含文件。 这表示文章适用于哪些 SQL Server 区域或版本。

请查看以下从 applies-to-version/sql-asdb-asa-pdw.md 包含文件中拉取的 Markdown 示例。

[!INCLUDE [SQL Server Azure SQL Database Synapse Analytics PDW](../includes/applies-to-version/sql-asdb-asdbmi-asa-pdw.md)]

这将在文章顶部添加以下文本：

Screenshot of Applies to text.

要为文章查找正确的“适用范围”include 文件，请参考以下提示：

  • 有关常用 include 的列表，请参阅 SQL Server 版本控制和 applies-to 的包含文件。
  • 查看包含相同功能或相关任务的其他文章。 如果编辑此文章，则可针对适用范围包含链接复制 Markdown（可取消编辑而不提交编辑）。
  • 针对包含文本“applies-to”的文件搜索 docs/includes 目录。 可使用 GitHub 中的“查找”按钮快速筛选。 选择文件，查看其呈现方式。
  • 注意命名约定。 如果名称包含字符串中的多个 x 字符，它们通常是占位符，表示缺少对服务的支持。 例如，appliesto-xx-xxxx-asdw-xxx-md.md 表示仅支持 Azure Synapse Analytics，因为仅拼写出了 asdw，而其他字段具有 x 内容。
  • 有些包含会指定一个版本号，例如 tsql-appliesto-ss2017-xxxx-xxxx-xxx-md.md。 仅当知道通过特定版本的 SQL Server 引入了此功能时才使用这些包含文件。

参与者资源

提示

如果有产品反馈而不是文档反馈，请在此处提供有关 SQL Server 产品的反馈。

相关内容

浏览 GitHub 上的 sql-docs 存储库。

查找文章，提交更改，并帮助 SQL Server 社区。

谢谢。