如何參與編輯 SQL Server 文件集

適用于:SQL Server Azure SQL Database Azure Synapse Analytics Analytics Platform System (PDW)

大家都可以參與編輯 SQL Server 文件集。 這包括修正錯字、建議更好的說明,以及提升技術正確性。 本文說明如何開始參與編輯內容以及程序的運作方式。

若要參與編輯,您可以使用下列兩個主要的工作流程:

工作流程 描述
在瀏覽器中編輯 適合簡短、快速編輯任何文章。
使用工具以在本機編輯 適用于更複雜的編輯、涉及多個文章的編輯,以及頻繁參與的編輯。

所有公開文章都會經過 SQL 內容小組的驗證,以確保技術方面的正確性與一致性。

在瀏覽器中編輯

您可以在瀏覽器中對 SQL Server 內容進行簡單的編輯,再提交到 Microsoft。 如需詳細資訊,請參閱 參與者指南概觀

下列步驟會摘要說明流程:

  1. 在您想提供意見反應的頁面上,選取位於右上角的 [編輯] 連結。
  2. 在下一個頁面上,選取位於右上角的鉛筆圖示。
  3. 在下一個頁面上,於 [編輯檔案] 文字視窗中,直接對您想要變更的文字進行編輯。 若您需要格式化新文字或變更後文字的協助,請參閱 Markdown 速查表
  4. 在您進行編輯後,請在 [認可變更] 下方:
    1. 在第一個文字方塊中,輸入您所進行變更的簡短描述。
    2. 在 [新增選擇性延伸描述] 方塊中,提供您變更的簡短描述。
  5. 選取 [建議檔案變更]。
  6. 在 [比較變更] 頁面上,選取 [建立提取要求]。
  7. 在 [開啟提取要求] 頁面上,選取 [建立提取要求]。

下列 GIF 會示範在您瀏覽器中提交變更的端對端過程:

編輯 SQL 文件

使用工具以在本機編輯

另一個編輯的選項是分叉 sql-docsazure-docs 存放庫,並將其複製到本機電腦。 接著,您可以使用 Markdown 編輯器以及 git 用戶端將變更送出。 此工作流程適合進行較複雜或包含多個檔案的編輯。 它也適用于 Microsoft 技術檔的頻繁參與者。

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

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

辨識

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

內容參與辨識

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 版本。

假設下列 Markdown 範例,其會在 appliesto-ss-asdb-asdw-pdw-md.md include 檔中提取。

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

這會將下列文字新增至文章的頂端:

適用於文字

若要為文章尋找正確的 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。
  • 某些 include 會指定版本號碼,例如 tsql-appliesto-ss2017-xxxx-xxxx-xxx-md.md。 當您知道某項功能是由特定版本的 SQL Server 導入時,請只使用該版本的 include。

參與者資源

秘訣

如果您想提供產品的意見反應,而不是文件意見反應,請在這裡提供 SQL Server 產品的意見反應

後續步驟

探索 GitHub 上的 sql-docs 存放庫

尋找文章、送出變更,並協助 SQL Server 社群。

感謝您!