如何参与编辑 SQL Server 文档

适用于:SQL Server Azure SQL 数据库 Azure Synapse Analytics 分析平台系统 (PDW)

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

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

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

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

在浏览器中编辑

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

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

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

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

编辑 SQL Docs 的屏幕截图。

使用工具在本地编辑

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

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

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

识别

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

内容编辑识别的屏幕截图。

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)]

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

“适用于”文本的屏幕截图。

要为文章查找正确的“适用范围”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 社区。

谢谢。