如何參與 SQL Server 文件

適用於:SQL ServerAzure SQL DatabaseAzure 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-docsazure-docs 存放庫,並將其複製到本機電腦。 接著,您可以使用 Markdown 編輯器以及 git 用戶端將變更送出。 此工作流程適合進行較複雜或包含多個檔案的編輯。 這也適合頻繁參與編輯 Microsoft 技術文件的使用者。

若要使用此方法參與編輯,請參閱下列文章:

如果您送出對文件集的重大變更提取要求時,就會收到一個 GitHub 註解,要求您提交線上的貢獻授權合約 (CLA)。 您必須填妥線上表單,系統才會接受您的提取要求。

辨識

如果系統接受您的變更,文章上方就會辨識您為參與者。

Screenshot of Content contribution recognition.

SQL-docs 概觀

本節提供在 sql-docs 存放庫中進行作業的其他指引。

重要

本節中的資訊專屬於 sql-docs。 如果您要編輯 Azure 文件中的 SQL 文章,請參閱 GitHub 中 azure-docs 存放庫的讀我檔案

sql-docs 存放區會使用數個標準的資料夾來組織內容。

資料夾 描述
docs 包含所有已發佈的 SQL Server 內容。 子資料夾會以邏輯方式組織內容的不同區域。
docs/includes 包含 include 檔案。 這些檔案是可能在一或多個其他文章中包含的內容區塊。
./media 每個資料夾都可以有一個 media 子資料夾,用來放置文章的影像。 media 資料夾中的子資料夾,其名稱與影像出現的文章名稱相同。 影像應該是 .png 檔案,檔名全為小寫字母且無空格。
TOC.MD 目錄檔案。 每個子資料夾都可以選擇使用一個 TOC.MD。

applies-to include 檔案

每篇 SQL Server 文章標題後都包含一個 applies-to include 檔案。 這表示該文章適用哪些領域或 SQL Server 版本。

請考慮下列在 applies-to-version/sql-asdb-asa-pdw.md include 檔案中提取的 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.

若要為文章尋找正確的 applies-to include 檔案,請使用下列祕訣:

  • 如需常用 include 檔案的清單,請參閱 SQL Server 版本和 applies-to 的 include 檔案
  • 查看其他涵蓋相同功能或相關工作的文章。 如果您要編輯這篇文章,可以複製 Markdown 以取得 applies-to include 連結 (您可以取消編輯而不送出)。
  • 搜尋 docs/includes 目錄,找出包含 applies-to 文字的檔案。 您可以使用 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 社群。

謝謝。