MSDN から docs.microsoft.com への .NET API ドキュメントの移行
''この投稿は、クラウドと AI 部門のプログラム マネージャーである Den Delimarsky によって執筆されました。''
11 ロケールにおいて、MSDN から docs.microsoft.com にすべての.NET Framework ドキュメントを完全に移行したことを発表します。 この移行のボリュームとスケールを理解するために、.NET Framework コンテンツには、900 万を超える API ドキュメント (つまり、MSDN ライブラリ全体のボリュームの 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 ブラウザー) を使用して、必要な API を数秒ですばやく見つけられるようにしました。
バージョン管理のサポート
特定のバージョンの .NET Framework または Azure Storage NuGet パッケージで使用可能なメンバーが特定のタイプに存在するかどうかを考える必要がなくなりました。必要なのは API ブラウザー コントロールからバージョンを変更することだけで、コンテンツはそれに応じて調整されます。
改善された構成
左側の目次では、コンテンツは名前空間とその名前空間内のエンティティの種類によってグループ化されています。 たとえば、クラスを選択すると、プロパティ、フィールド、メソッド、およびイベントの各タイプによってエンティティがグループ化されていることがわかります。
あるいは、.NET API ブラウザーを利用して検索することもできます。また、目次から特定の API バージョンをすべてフィルター処理して、探している正確な API を簡単に見つけられるようにすることもできます。
API リファレンス ページ内では、API に関するダウンロード、セットアップ、およびその他の役立つドキュメントを見つけることが困難な場合があります。 次の画像に示すように、Azure .NET SDK では、記事とリファレンス ドキュメントの両方が 1 つの目次にまとめられています。
直感的な 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 言語がサポートされます
ブラウザーでサンプルを対話的に実行する
コードを使用する際に、学習する最善の方法は実際にコードを記述することです。Microsoft では、お客様がブラウザーから適切に実行できることを確認したいと考えていました。 1 年前に、「.NET 機能を試す」を公開し、その年を通じて、多くの記事に統合しました。 今後、継続的にこの機能をさらに多くの API ドキュメントに統合することで、ページを離れずに試せるようになります。
標準の自動生成ツールでのサポート
docs.microsoft.com のすべての API ドキュメントが自動的に生成されるため、API サーフェス全体を簡単に文書化できるだけでなく、更新の時間と頻度を数週間から数分にして大幅に向上させることができます。 これにより、すべての .NET API について、質の高い API ドキュメントを確実に取得できます。
これを行うために、Xamarin エンジニアリング チームと提携し、mdoc を開発して使用し、すべての .NET リファレンス ドキュメントを生成しました。
MSDN リンク - docs.microsoft.com へのリダイレクト
移行を開始したときに、リンクが壊れていないことを確かめる必要がありました。つまり、製品、ブログ投稿およびその他のサイトに統合される可能性のあるすべての MSDN リンクが正常に機能し、ユーザーに標準の 301 リダイレクトを利用して新しい場所を指し示す必要があります。
コミュニティに貢献する準備が整いました
移行されたすべてのコンテンツは、GitHub の dotnet/dotnet-api-docs リポジトリでオープン ソースになりました。 しかし、貢献するためにファイルを検索する必要はありません。 .NET API のいずれかのページに移動して、[編集] をクリックするだけで、変更を加えるファイルが直接表示されます。
