この投稿は、クラウド + AI 部門のプログラム マネージャー Den Delimarskyによって書かれています。
MSDN から docs.microsoft.comへの 11 ロケールのすべての .NET Framework ドキュメントの移行が完了したことをお知らせします。 この移行のボリュームとスケールを理解するために、.NET Framework のコンテンツは、MSDN ライブラリ全体 900 万以上の API ドキュメントまたは 20% を表します。
目標は、Microsoft が提供するすべての .NET API を検索して移動するための統一された最新の一貫性のあるエクスペリエンスを提供すること、バージョン管理の詳細なサポート、API コード サンプルの使用と実行、自動化を使用した API 更新の容易な有効化、コミュニティへの貢献のサポートを提供することです。
docs.microsoft.com は、次の場合にこのエクスペリエンスを有効にします。
- .NET Framework (バージョン 1.1 から 4.7.2)
- .NET Core (バージョン 1.0 から 2.1)
- .NET Standard (バージョン 1.0 から 2.0)
- また、Microsoft から出荷されるすべての .NET API、SDK、NuGet パッケージ
.NET API ブラウザーを使用して、すべての Microsoft .NET API を 1 か所で検索する
API を探しているが、どこから始めればいいかわからない状況にありましたか? 専用の API 検索インデックスを構築しました。これにより、製品とバージョンのフィルター (.NET API Browser) を使用して、必要な API をすばやく数秒で見つけることができます。
.NET API ブラウザーの検索する
バージョン管理のサポート
特定のバージョンの .NET Framework または Azure Storage NuGet パッケージで使用できるメンバーが型にあるかどうか疑問に思う必要がなくなりました。必要なのは、API Browser コントロールからバージョンを変更するだけで、コンテンツはそれに応じて調整されます。
.NET ドキュメントのバージョン ピッカーの 
組織の改善
左側の目次では、コンテンツは名前空間と、その名前空間内のエンティティの種類によってグループ化されます。 たとえば、クラスを選択すると、エンティティをそれぞれの種類 (Properties、Fields、Methods、Events) でグループ化していることがわかります。
または、.NET API Browser を使用して検索したり、目次から特定の API バージョンをフィルター処理したりして、探している正確な API を簡単に見つけることもできます。
また、API リファレンス ページ内にいる場合、API のダウンロード、セットアップ、その他の役に立つドキュメントを見つけるのが難しい場合もあると、お客様から言われました。 次の図に示すように、Azure .NET SDK では、記事とリファレンス ドキュメントの両方が 1 つの目次にまとめられます。
Azure API
直感的な URL
最初に docs.microsoft.comを起動したとき、目標の 1 つは、明確で一貫性があり、直感的な階層 URL を持つことでした。 MSDN の使用を思い出すと、一部の .NET URL は次のように構成されていました。
https://msdn.microsoft.com/library/8kszeddc(v=vs.110).aspx
見るだけで、このコンテンツが何であるかを理解するのが本当に難しかったです。
上記のリンクは次のようになります。
https://docs.microsoft.com/dotnet/api/system.array.sort
.NET の一貫性と直感的な URL を確保するために URL ブックの URL 規則の一部を次に示します。
名前空間
パターン: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}
例の: https://docs.microsoft.com/dotnet/api/system.collections.generic/
クラス
パターン: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}
例の: https://docs.microsoft.com/dotnet/api/system.flagsattribute
メソッド
パターン: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}.{method}
例の: https://docs.microsoft.com/dotnet/api/system.decimal.add
最初の例
お客様へのインタビューから一貫して聞いたことの 1 つは、API の高品質、簡潔、機能的なコード例の重要性です。 MSDN では、ページの末尾に例が含まれています。つまり、一部の例では、型の最初の例を表示するには、20 回以上下にスクロールする必要があります。 Docs では、最初に例を次に示します。
の例の比較
MSDN と同様に、Docs では、C#、VB、F#、C++ を含むすべての .NET 言語がサポートされています
ドキュメントする
ブラウザーで対話的に例を実行する
コードを操作する場合、学習する最善の方法は、実際にコードを記述することです。ブラウザーから直接実行できるようにしたいと考えていました。 1 年前に、Try .NET 機能をロールアウトし、その年を通してさまざまな記事に統合しました。 今後も、この機能をさらに多くの API ドキュメントに統合し、ページを離れることなく実験できるようにします。
ブラウザーする
標準の自動生成ツールでサポート
docs.microsoft.com に関するすべての API ドキュメントが自動的に生成されるため、API サーフェス全体を簡単に文書化でき、更新の時間と頻度が数週間から数分に劇的に向上します。 これにより、すべての .NET API に関する高品質の API ドキュメントを取得できます。
これを行うために、Xamarin エンジニアリング チームと提携し、mdoc を開発して使用し、すべての .NET リファレンス ドキュメントを生成しました。
MSDN のリンク - docs.microsoft.com へのリダイレクト
移行を開始する前に、リンクが壊れていないことを確認する必要がありました。製品、ブログの投稿、その他のサイトに統合されているすべての MSDN リンクは正常に動作し、標準の 301 リダイレクトの助けを借りて、ユーザーを新しい場所に向ける必要があります。
MSDN から docs.microsoft.comリダイレクト
コミュニティへの投稿の準備
移行されたすべてのコンテンツは、GitHub の dotnet/dotnet-api-docs リポジトリでオープン ソースになりました。 ただし、投稿を行うためにファイルを検索する必要はありません。.NET API ページに移動して [の編集]クリックするだけで、変更するファイルに直接移動します。
