SQL Server のドキュメントに投稿する方法

  • [アーティクル]

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

誰でも SQL Server のドキュメントに投稿できます。 投稿には、入力ミスの修正、もっとよい説明の提案、技術的正確さの改善などがあります。 この記事では、コンテンツへの投稿の概要とプロセスについて説明します。

2 つの主要なワークフローを使って投稿することができます。

ワークフロー 説明
ブラウザーで編集する 任意の記事のちょっとした編集を簡単に行うのに適しています。
ツールを使ってローカルに編集する 複雑な編集、複数の記事が関係する編集、頻繁な投稿に適しています。

SQL コンテンツ チームは、公開されるすべての投稿を技術的正確さと一貫性について検証します。

ブラウザーで編集する

お使いのブラウザーで SQL Server のコンテンツに簡単な編集を加え、Microsoft に送信することができます。 詳細については、「共同作成者ガイド概要」を参照してください。

次の手順は、このプロセスをまとめたものです。

  1. フィードバックがあるページで、右上の [鉛筆] アイコンを選択します。
  2. 次のページで、右上の鉛筆アイコンを選択します。 このアイコンが表示されない場合は、まず GitHub アカウントにサインインする必要があります。
  3. 次のページの [Edit file](ファイルの編集) テキスト ウィンドウで、変更するテキストを直接編集します。 新規または変更されたテキストの書式設定に関するヘルプが必要な場合は、「Markdown Cheatsheet」(マークダウンのカンニング ペーパー) を参照してください。
  4. 編集が完了したら、[変更のコミット] で次の手順を実行します。
    1. 最初のテキスト ボックスに、行った変更の簡単な説明を入力します。
    2. [Add an optional extended description](省略可能な長い説明を追加する) ボックスに、変更の簡単な説明を入力します。
  5. [Propose file change](ファイルの変更の提案) を選択します。
  6. [Comparing changes](変更の比較) ページで、 [Create pull request](プル要求の作成) を選択します。
  7. [Open a pull request](プル要求を開く) ページで、 [Create pull request](プル要求の作成) を選択します。

次の GIF は、お使いのブラウザーで変更を送信するためのエンドツーエンド プロセスを示しています。

[SQL ドキュメントの編集] のスクリーンショット。

ツールを使ってローカルに編集する

もう 1 つの編集オプションは、sql-docs または azure-docs リポジトリをフォークして、お使いのコンピューターにローカルに複製します。 その後、Markdown エディターと git クライアントを使って、変更を送信することができます。 このワークフローは、複雑で複数のファイルが関係する編集に適しています。 Microsoft 技術ドキュメントに頻繁に投稿する人にも適しています。

この方法で投稿する場合は、次の記事を参照してください。

ドキュメントを大幅に変更する pull request を送信する場合は、オンライン貢献者使用許諾契約書 (CLA) の提出を求める GitHub のコメントを受け取ります。 オンライン フォームを提出してからでないと、pull request は受け付けられません。

認識

変更が受け付けられると、記事の上部で共同作成者として認識されます。

コンテンツへの投稿の認識のスクリーンショット。

sql-docs の概要

このセクションでは、sql-docs リポジトリでの作業に関する詳細なガイダンスを提供します。

重要

このセクションの情報は、sql-docs に固有のものです。 Azure のドキュメントに含まれる SQL の記事を編集する場合は、GitHub で azure-docs リポジトリの Readme を参照してください。

sql-docs リポジトリでは、複数の標準フォルダーを使ってコンテンツが整理されています。

Folder 説明
docs 公開されたすべての SQL Server コンテンツが格納されています。 サブフォルダーには、異なる分野のコンテンツが論理的にまとめられています。
docs/includes インクルード ファイルが格納されています。 これらのファイルは、他の記事に含めることのできるコンテンツのブロックです。
./media 各フォルダーには、記事の画像用に 1 つの media サブフォルダーが含まれる場合があります。 media フォルダーには、画像が表示される記事と同じ名前のサブフォルダーがあります。 画像は .png ファイルで、すべて小文字のスペースを含まない名前になっている必要があります。
TOC.MD 目次のファイルです。 各サブフォルダーでは、1 つの TOC.MD ファイルを使うことができます。

applies-to インクルード

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

このインクルード ファイルにより、記事の上部に次のテキストが追加されます。

Applies to テキストのスクリーンショット。

記事の適切な applies-to インクルード ファイルを探すには、次のヒントを参考にしてください。

  • 一般的に使用されるインクルードの一覧は、SQL Server のバージョン管理と applies-to のインクルード ファイルに関するページを参照してください。
  • 同じ機能または関連タスクをカバーしている他の記事を探します。 その記事を編集する場合は、applies-to インクルード リンクの Markdown をコピーできます (送信しないで編集をキャンセルできます)。
  • docs/includes ディレクトリで、applies-to というテキストを含むファイルを探します。 GitHub の [Find] (検索) ボタンを使ってすばやくフィルター処理できます。 ファイルを選択して、どのようにレンダリングされるかを確認します。
  • 名前付けの規則に注意してください。 名前の文字列に複数の x 文字が含まれる場合は、それらは通常、サービスのサポートがないことを示すプレースホルダーです。 たとえば、appliesto-xx-xxxx-asdw-xxx-md.md は、asdw だけが明示され、他のフィールドは x になっているので、Azure Synapse Analytics のみのサポートであることを示しています。
  • 一部には、tsql-appliesto-ss2017-xxxx-xxxx-xxx-md.md などのバージョン番号の指定が含まれます。 SQL Server の特定のバージョンで機能が導入されたことがわかっている場合は、それらのインクルード ファイルだけを使ってください。

共同作成者のリソース

ヒント

ドキュメントに関するフィードバックではなく製品のフィードバックの場合は、こちらで SQL Server 製品に関するフィードバックを提供してください。

関連するコンテンツ

GitHub で sql-docs リポジトリを調べます。

記事を探し、変更内容を送信して、SQL Server コミュニティに投稿します。

ありがとうございます。