Visual C++ ドキュメントへの貢献に関心をお寄せいただきありがとうございます。
このトピックでは、Visual C++ ドキュメント サイトのコンテンツを追加または更新するための基本プロセスについて説明します。
このトピックの内容:
手順 1: 作成する記事と既存のコンテンツとの関連を説明する問題を開きます。 docs フォルダー内の内容は、コンテンツ領域 (デバッガーなど) 別に編成されたセクションに編成されています。 新しいコンテンツ用の適切なフォルダーを特定します。 提案に対するフィードバックを得ます。
小さな変更の場合はこの最初の手順をスキップできます。
手順 2: MicrosoftDocs/cpp-docs リポジトリをフォークします。
手順 3: 記事の branch を作成します。
手順 4: 記事を作成します。
新しいトピックの場合は、このテンプレート ファイルを開始点として使用できます。 このファイルには、作成のガイドラインが含まれ、作成者情報など、記事ごとに必要なメタデータについても説明されています。
手順 1 で、ご自分の記事について特定した TOC の場所に対応するフォルダーに移動します。 そのフォルダーには、そのセクション内のすべての記事のマークダウン ファイルが格納されています。 必要に応じて、ご自分のコンテンツ用のファイルを格納する新しいフォルダーを作成します。
イメージとその他の静的リソースについては、media という名前のサブフォルダーに追加します。 コンテンツ用の新しいフォルダーを作成する場合は、新しいフォルダーに media フォルダーを追加します。
適切なマークダウン構文に従ってください。 詳細については、スタイル ガイドを参照してください。
docs
/standard-library
wstring-convert-class.md
/media
wstring-conversion.png
手順 5: ご自分のブランチから MicrosoftDocs/cpp-docs/master にプル要求 (PR) を送信します。
PR が既存の問題に対処している場合は、コミット メッセージまたは PR の説明に Fixes #Issue_Number キーワードを追加すると、PR がマージされたときに問題が自動的に閉じられます。 詳細については、コミット メッセージによって問題を閉じる方法についての記事を参照してください。
Visual Studio チームが PR を確認し、変更が適切であるか、または変更を承認するために必要な他の更新や変更があるかどうかをお知らせします。
手順 6: チームによって説明されたとおりに、ご自分のブランチに必要な更新を加えます。
フィードバックが適用され、変更が適切であるように見える場合は、保守管理者によって、PR がマスター ブランチにマージされます。
特定の周期で、マスター ブランチのすべてのコミットがライブ ブランチにプッシュされるので、docs.microsoft.com でライブでご自分の投稿を確認できます。
.NET ドキュメントに投稿する際に注意する必要があるガイド ルールの簡単な一覧を次に示します。
- 突然に、巨大なプル要求を送信しないでください。 代わりに、問題を提出し、ディスカッションを開始して、大量の時間を費やす前に方向について同意が得られるようにしてください。
- スタイル ガイドとスタイルとトーンのガイドラインをお読みください。
- テンプレート ファイルを作業の開始点として使用してください。
- 記事に取り掛かる前に、フォークに個別のブランチを作成してください。
- GitHub フロー ワークフローに従ってください。
- 投稿について頻繁にブログやツイートを書いてください。
Note
一部のトピックが現在、この記事やスタイル ガイドに指定されたすべてのガイドラインに従っていないことに気付く場合があります。 Microsoft では、サイト全体で一貫性の達成に向けて取り組んでいます。 その特定の目標に向けて現在追跡中の未解決の問題の一覧をご確認ください。
ドキュメントは、GitHub Flavored Markdown を使用して書かれており、DocFX とその他の内部公開/構築ツールを使用して構築されています。 ドキュメントは、docs.microsoft.com でホストされています。
ドキュメントをローカルで構築する場合は、DocFX をインストールする必要があり、この最新バージョンが最適です。
DocFX を使用する方法はいくつかありますが、そのほとんどは、DocFX のファースト ステップ ガイドに記載されています。 次の手順では、コマンド ライン ベースのバージョンのツールを使用しています。 上記のリンクに記載されている他の方法が使いやすい場合は、それらを使用してもかまいません。
注: 現在、DocFX には Windows または Mono (Linux または macOS 用) 上の .NET Framework が必要です。 将来 .NET Core に移植されることが望まれます。
組み込みの Web サーバーを使用して、ローカルで結果のサイトをビルドしてプレビューできます。 コンピューター上の cpp-docs\docs フォルダーに移動し、次のコマンドを入力します。
docfx -t default --serve
これにより、localhost:8080 でローカル プレビューが起動されます。 変更を表示するには、http://localhost:8080/[path] (http://localhost:8080/cpp/visual-cpp-in-visual-studio.html など) に移動します。
注: ローカル プレビューには現在のところテーマが含まれないため、ドキュメント サイト内とルック アンド フィールが同じになりません。 この操作については修正中です。 プレビューでは表示されない、埋め込みのビデオ、ノート、含まれているドキュメントに対してはカスタム拡張機能も使用します。
現在のところ、必要なサンプル コードはインライン コード ブロックとして記事に含めます。 リポジトリには codesnippets フォルダーがありますが、これは公開投稿向けに準備されていません。
PR がマージされる前に、貢献者使用許諾契約書 (CLA) に署名する必要があります。 これは、docs.microsoft.com 内のプロジェクトに対して 1 回だけ必要です。 貢献者使用許諾契約書 (CLA) について詳しくは、Wikipedia を参照してください。
前もって契約に署名する必要はありません。 PR は通常どおり、複製、フォーク、送信できます。 PR が作成されると、CLA ボットで分類されます。 変更が軽微である (入力ミスの修正など) 場合は、PR に CLA-not-required のラベルが付けられます。 それ以外の場合は、CLA-required と分類されます。 CLA への署名後は、現在以降のすべての pull requests に、CLA-singed のラベルが付けられます。