如何参与编辑 SQL Server 文档How to contribute to SQL Server Documentation

适用于: 是SQL Server 是Azure SQL 数据库 是Azure Synapse Analytics(SQL 数据仓库)是并行数据仓库 APPLIES TO: YesSQL Server YesAzure SQL Database YesAzure Synapse Analytics (SQL Data Warehouse) YesParallel Data Warehouse

任何人都可以参与编辑 SQL Server 文档。Anyone can contribute to SQL Server documentation. 这包括更正拼写错误、提出更好的解释以及改进技术的准确性。This includes correcting typos, suggesting better explanations, and improving technical accuracy. 本文介绍如何开始参与内容编辑以及此过程的工作原理。This article explains how to get started with content contributions and how the process works.

可通过以下两个主要工作流参与编辑:There are two main workflows you can use to contribute:

工作流Workflow 说明Description
在浏览器中编辑Edit in your browser 适用于对任何文章进行少量快速编辑。Good for small, quick edits of any article.
使用工具在本地编辑Edit locally with tools 适用于更复杂的编辑、涉及多篇文章的编辑,以及针对 docs.microsoft.com 的频繁编辑。Good for more complex edits, edits involving multiple articles, and frequent contributions to docs.microsoft.com.

SQL 内容团队会对所有公开发表的内容进行验证,以确保技术准确性和一致性。All public contributions are validated by the SQL content team for technical accuracy and consistency.

在浏览器中编辑Edit in your browser

可以在浏览器中对 SQL Server 内容进行简单编辑,然后将其提交到 Microsoft。You can make simple edits to SQL Server content in your browser and then submit them to Microsoft. 有关详细信息, 请参阅 Microsoft Docs 参与者指南概述For more information, you can see the Microsoft Docs contributor guide overview.

以下步骤概述了这一过程:The following steps summarize the process:

  1. 在要进行反馈的页面上,选择右上角的“编辑”链接。On the page you have feedback about, select the Edit link at the top right.
  2. 在下一页中,选择右上角的铅笔图标。On the next page, select the Pencil icon at the top right.
  3. 在下一页上的“编辑文件”文本窗口中,对要更改的文本直接进行编辑。On the next page, in the Edit file text window, make your edits directly to the text you want to change. 如果需要有关对新文本或更改的文本设置格式的帮助,请参阅 Markdown 速查表If you need help with formatting the new or changed text, see the Markdown Cheatsheet.
  4. 进行编辑之后,请在“提交更改”下:After you've made your edits, under Commit changes:
    1. 在第一个文本框中,输入所进行的更改的简要说明。In the first text box, enter a brief description of the change you've made.
    2. 在“添加一个可选的扩展说明”框中,提供对更改的简短解释。In the Add an optional extended description box, provide a brief explanation of your change.
  5. 选择“建议文件更改”。Select Propose file change.
  6. 在“比较更改”页面上,选择“创建拉取请求”。On the Comparing changes page, select Create pull request.
  7. 在“打开拉取请求”页面上,选择“创建拉取请求”。On the Open a pull request page, select Create pull request.

下面的 GIF 演示了在浏览器中提交更改的完整过程:The following GIF demonstrates the end-to-end process for submitting changes in your browser:

编辑 SQL 文档

使用工具在本地编辑Edit locally with tools

另一个编辑选项是创建 sql-docs 或 azure-docs 存储库的分支并将其克隆到本地计算机 。Another editing option is to fork the sql-docs or azure-docs repositories and clone it locally to your machine. 然后可以使用 Markdown 编辑器和 git 客户端提交所做的更改。You can then use a Markdown editor and a git client to submit the changes. 此工作流适用于更复杂或涉及多个文件的编辑。This workflow is good for edits that are more complex or involve multiple files. 另外,它也适用于针对 docs.microsoft.com 的频繁参与者。It is also good for frequent contributors to docs.microsoft.com.

若要使用此方法参与编辑,请参阅以下文章:To contribute with this method, see the following articles:

如果提交包含对文档的重大更改的拉取请求,则将在 GitHub 中收到一条注释,要求提交联机“贡献许可协议 (CLA)”。If you submit a pull request with significant changes to documentation, you will get a comment in GitHub asking you to submit an online Contribution License Agreement (CLA). 必须先完成联机窗体,然后系统才会接受你的拉取请求。You must complete the online form before your pull request can be accepted.

识别Recognition

如果接受了你所做的更改,则系统会在文章顶部将你识别为参与者。If your changes are accepted, you are recognized as a contributor at the top of the article.

内容编辑识别

sql-docs 概述sql-docs overview

本部分提供一些有关在 sql-docs 存储库中工作的其他指导。This section provides some additional guidance on working in the sql-docs repository.

重要

本部分中的信息特定于 sql-docs。若要编辑 Azure 文档中的 SQL 文章,请参阅 GitHub 上 azure-docs 存储库的自述文件The information in this section is specific to sql-docs. If you are editing a SQL article in the Azure documentation, see the Readme for the azure-docs repository on GitHub.

sql-docs 存储库使用多个标准文件夹来组织内容。The sql-docs repository uses several standard folders to organize the content.

FolderFolder 说明Description
docsdocs 包含所有已发布的 SQL Server 内容。Contains all published SQL Server content. 子文件夹有逻辑地组织内容的不同区域。Subfolders logically organize different areas of the content.
docs/includesdocs/includes 包括包含文件。Contains include files. 这些文件是可以包含在一个或多个其他主题中的内容块。These files are blocks of content that can be included in one or more other topics.
./media./media 每个文件夹可以有一个用于文章图像的“媒体”子文件夹。Each folder can have one media subfolder for article images. “媒体”文件夹又包含名称与图像出现的主题名称相同的子文件夹。The media folder in turn has subfolders with the same name as the topics that the image appears in. 图像应为字母全部小写且没有空格的 .png 文件。Images should be .png files with all lower-case letters and no spaces.
TOC.MDTOC.MD 目录文件。A table-of-contents file. 每个子文件夹都可选择使用 TOC.MD 文件。Each subfolder has the option of using one TOC.MD file.

“适用范围”包含Applies-to includes

每篇 SQL Server 文章的标题后都包含“适用范围”包含文件。Each SQL Server article contains an applies-to include file after the title. 这表示文章适用于哪些 SQL Server 区域或版本。This indicates what areas or versions of SQL Server the article applies to.

请查看以下从 appliesto-ss-asdb-asdw-pdw-md.md 包含文件中拉取的 Markdown 示例。Consider the following Markdown example that pulls in the appliesto-ss-asdb-asdw-pdw-md.md include file.

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

这将在文章顶部添加以下文本:This adds the following text at the top of the article:

“适用范围”文本

要为文章查找正确的“适用范围”include 文件,请参考以下提示:To find the correct applies-to include file for your article, use the following tips:

  • 有关常用 include 的列表,请参阅 SQL Server 版本和 applies-to include文件For a list of commonly used includes, see SQL Server version and applies-to include files.
  • 查看包含相同功能或相关任务的其他文章。Look at other articles that cover the same feature or a related task. 如果编辑此文章,则可针对适用范围包含链接复制 Markdown(可取消编辑而不提交编辑)。If you edit that article, you can copy the Markdown for the applies-to include link (you can cancel the edit without submitting it).
  • 针对包含文本“适用范围”的文件搜索 docs/includes 目录。Search the docs/includes directory for files containing the text "applies-to". 可使用 github 中的“查找”按钮快速筛选。You can use the Find button in github to quickly filter. 单击文件,查看其呈现方式。Click on the file to see how it is rendered.
  • 注意命名约定。Pay attention to the naming convention. 如果名称中包含 x,它们通常是占位符,表示缺少对服务的支持。If there are x's in the name, they are usually placeholders indicating the lack of support for a service. 例如,appliesto-xx-xxxx-asdw-xxx-md.md 表示仅支持 Azure SQL 数据仓库,因为仅拼写出了 asdw,而其他字段具有 x 。For example, appliesto-xx-xxxx-asdw-xxx-md.md indicates support for only Azure SQL Data Warehouse, because only asdw is spelled out, whereas the other fields have x's.
  • 某些包含指定了版本号,如 tsql-appliesto-ss2017-xxxx-xxxx-xxx-md.md。Some includes specify a version number, such as tsql-appliesto-ss2017-xxxx-xxxx-xxx-md.md. 仅当知道通过特定版本的 SQL Server 引入了此功能时才使用这些包含。Only use these includes when you know the feature was introduced with a specific version of SQL Server.

参与者资源Contributor resources

提示

如果有产品反馈而不是文档反馈,请在此处提供有关 SQL Server 产品的反馈If you have product feedback rather than documentation feedback, provide feedback on the SQL Server product here.

后续步骤Next steps

浏览 GitHub 上的 sql-docs 存储库Explore the sql-docs repository on GitHub.

查找文章,提交更改,并帮助 SQL Server 社区。Find an article, submit a change, and help the SQL Server community.

谢谢!Thank you!