docs.microsoft.com の 11 月の更新プログラム
この投稿は、クラウドおよびエンタープライズ事業部の統括部長、Jeff Sandquist によって執筆されました。
本日、Linux 上の Azure、Visual Studio 2017 RC、C++、ASP.NET Core、Entity Framework Core、および SQL を対象にしたドキュメントを docs.microsoft.com に移行しましたのでご報告いたします。
すべてのコンテンツを 1 つに統合することにより、モバイル サポート、ローカリゼーション、コメント、ソーシャル共有、またはコミュニティからの投稿に対するお客様のエクスペリエンスの一貫性が向上します。
これは大規模なリリースですが、引き続きコンテンツとサイト機能を定期的に更新していきますので、コンテンツ エクスペリエンスに関する UserVoice フィードバック をぜひお寄せください。
また、Dynamics 365、Windows Server、SQL Server、System Center、および Windows デスクトップ向けのコンテンツも、今後数か月間に追加されますのでご期待ください。
- ドキュメントの主な機能
- ドキュメントの新機能
- Azure ドキュメント
- Visual Studio 2017 RC ドキュメント
- C++ ドキュメント
- ASP.NET Core ドキュメント
- Entity Framework Core ドキュメント
- Linux 上の SQL のドキュメント
docs.microsoft.com になじみのないお客様のために、新しいエクスペリエンスの主な機能についていくつか紹介します。
簡単ではありますが、ご意見を基に、記事を読むのにかかる推定時間を追加しました。 ミーティングの合間の数分間でテクノロジについて調査と評価を行っている方が多く、所要時間がわかれば記事を読む気が増すことでしょう。
また、コンテンツの更新内容を把握できるようにコンテンツにタイム スタンプも追加しましたので、記事がいつ最終更新されたかを推測する必要はなくなりました。
モバイル デバイス、タブレット、および PC でのエクスペリエンス改善についてのご要望を反映するために、レスポンシブ レイアウトを実装しました。 小さな画面のデバイス上のページの上部にある [オプション] ボタンをクリックすると、デスクトップのブラウザーで表示されるものと同じオプションにアクセスできます。
ローカライズされたコンテンツの重要性について、海外のお客様から何度もご意見をお寄せいただいております。 現在、docs.microsoft.com は、アラビア語やヘブライ語などの右から左へ記述する言語を含む 45 の言語に加え、ローカライズされたドキュメントが利用できない可能性のあるフォールバック ロジックを含む Dynamics 365 コンテンツ向けに合計で 63 のロケールをサポートしています。 これにより、ドキュメントが真にグローバル化され、新年に予定されている追加コンテンツの準備を整えています。
皆様からお寄せいただく質問、コメント、フィードバックは私たちにとって欠かせないものです。 Livefyre と協力し、すべての記事にコメントとミニ ノートを追加しました。 コメント セクションに直接ジャンプするためのオプションが、すべての記事の上部に表示されます。
ご意見をぜひお寄せください。ドキュメント ページ上に残されたすべてのコメントとご質問を拝見し、返信にするよう努めています。
コメントをするには、既存の Twitter、Facebook、Google、yahoo!、または Microsoft の資格情報を使用してログオンできます。
さらに、お客様はフォローアップを望むスレッドをフォローできますので、チームまたはコミュニティのいずれかのメンバーがお客様に返信したことを常に把握できます。
また、コンテンツの各段落やハイライトで指定したテキストにミニ ノートを追加することもできます。 これは、マウス カーソルでテキストのチャンクを選択するか、マウス カーソルを合わせると段落の右側に表示される [コメント] アイコンをクリックするだけで実行できます。
ページ上部にある [共有] ボタンを使用すると、コンテンツを Twitter のフォロワーおよび Facebook の友だちと簡単に共有できます。
マウスでコンテンツを直接選択して、コンテキスト ウィジェットを使用して共有することもできます。
また、一部 [asked for on UserVoice](https://msdocs.uservoice.com/forums/364242-general-site-feedback/suggestions/14999211-komplete-dark-theme)
のユーザーが持っているものである、明るいテーマと暗いテーマの間で変更できるように、テーマ ピッカーも追加されました。
私たちは Web エクスペリエンスを重視しており、TechNet と MSDN を利用する際に直面する日頃の悩みの種の 1 つとして、記事の URL がわかりづらく読みづらいことが挙げられます。 同じ記事について、新しい URL の例を次に示します。
https://technet.microsoft.com/library/dn646983.aspx3
https://docs.microsoft.com/intune/get-started/start-with-a-paid-subscription-to-microsoft-intune
サイト上にあるドキュメントの大部分はコミュニティからの投稿が有効になっています。 右上のメニューにある [編集] ボタンをクリックするだけで、対応する GitHub ページに移動して、リポジトリをフォークし、変更を加え、pull request を送信できます。 ローカライズされたコンテンツの編集や投稿のエクスペリエンス全体に関するフィードバックもお待ちしております。
これらの機能の多くは 5 月の製品発表日以来ある機能ですが、以下に示す多くの新しい機能も追加されました。
目次を即時にフィルターできるようにしました。 つまり、これにより数文字を入力するだけで、一致するテキストをフィルターして、探しているコンテンツを簡単に検索することができます。
追加した別の主要機能は、複数のサイト上のコンテンツに関する問題に対処します。 Azure App Service への ASP.NET アプリの展開に関する記事を Azure または ASP.NET のいずれかの下に一覧表示する必要がありますか。 答えは両方です。ただし、見つけやすさと一貫性のために両方のサイト セクションでコンテンツを複製する必要はありません。
これを行うために、コンテンツ チームがドキュメント上の任意のコンテンツを選択し、お客様のコンテンツのビューを作成できるようにしています。 以下の画像は、Azure、ASP.NET、.NET Core、および Visual Studio Azure SDK のチームから配信されるコンテンツを含む Docker を使用して、.NET 開発者に対して架空のレイアウトがどのように、すべて 1 つのビューで表示されるのかを示しています。
ドキュメントの最もストレスの溜まる機能の 1 つは、提示されたサンプルや、リンクされているサンプルが実際にはコンピューター上で動作しない場合です。 Microsoft では、数千ものコード サンプルとスニペットを用意しており、これらのサンプルがサポートされているプラットフォームと構成で動作することをお客様に信頼していただけるよう尽力しています。
このため、拡張可能な継続的インテグレーション (CI) システムを開発し、常にサンプルによってオペレーティング システム、ツール チェーンの指定されたセットに対して予期される出力がコンパイルされ、生成されるようにしました。 より多くのチームがこれに参加するように取り組むと同時に、コードをダウンロードするユーザーが自信をもってすべての必要な品質チェックに確実に合格できるように努めています。
さまざまなプラットフォームと形式用の言語バインドを含めるため、docs.microsoft.com を機能させるオープンソースのコンポーネントである、基になる DocFX エンジンを再設計しました。 これには、次のサポートが含まれます。
- Azure CLI (Python)
- PowerShell
- .NET と .NET Core
- Java
- Swagger / REST API
これはお客様にとって、ドキュメントとコードの両方を機能させる情報が一元化されたことで、ドキュメントに API 機能と同期していない誤差がなくなることを意味しています。 API リファレンスの特定のサポートの詳細については、後述の Azure と ASP.NET/EF のセクションでお読みいただけます。
お客様からご要望のあった別の主な機能は、PDF のサポートです。ギガバイトの領域を使用することなく特定のドキュメントのセットをダウンロードして、デスクトップであってもモバイル デバイスであっても、あらゆる場所に持ち運ぶことができます。
これを可能にするために、目次の PDF サポートを有効にしました。 ライブ サイトでコンテンツが更新されると、PDF ファイルが更新されることを確認していますので、お客様は最新で最高のコンテンツを常時入手できます。
<img alt="screenshot16]()
エクスペリエンスに基づく断片化と課題に関してお客様からフィードバックをお寄せいただいています。これに対応するため、Azure の技術文書を azure.microsoft.com、MSDN、および GitHub から移行して、https://docs.microsoft.com/azure/ に統合する作業を順調に進めています。
この機会を利用して、Azure コンテンツのランディング ページの外観も変更しました。 主な要点をいくつか以下に示します。
- カテゴリごとにまとめられた Azure サービスを一覧表示する [サービス] タブ。
- REST API、Azure .NET SDK、Azure Java SDK、Azure CLI、および Azure PowerShell のすべての Azure リファレンスのコンテンツを一覧表示する [開発者] タブ。
- 設計者と開発者がクラウド スケールのデザイン パターンについて学習するための [アーキテクチャ] タブ。
ランディング ページには一貫性を持たせ、次のような主要なリソースへのリンクを配置しました。
- サービスの概要リンク。
- すべての関連するプラットフォームおよびプログラミング言語の 作業の開始チュートリアル。
- 指定されたサービスのすべてのビデオ チュートリアルへのリンク。
- API リファレンスのコンテンツへのリンク。
- そのサービスのすべてのドキュメントをダウンロードするためのリンク。
docs.microsoft.com/azure への移行を進めると同時に、この機会を利用して、目次ナビゲーションの一貫性の向上に取り組んでいます。 サービスにはそれぞれ固有の特性がありますが、サイト間を移動するときに類似したナビゲーションが表示されるようになります。
Azure コマンド ライン インターフェイス (CLI) を表すコード サンプルに対して、コードを簡単に読めて理解できるよう、キーワードとパラメーターに色づけを追加しました。
すべてのお客様からご意見をいただいていた最大の問題点の 1 つは、API、コマンド ライン、および PowerShell コンテンツが最新のものではないということです。 Azure の急速な変更に伴い、従来の手動によるワークフローは機能しなくなりました。
このリリースでは、ソース コードから直接リファレンスを作成するようシステムを変更しました。 新しいビルドが配信されると、新しいコンテンツも配信されます。 また、[操作手順] コンテンツへの投稿と同じように、ドキュメントの自動生成された部分に対しても同様の操作が可能です。
Open API Specification (旧 Swagger) の使用も標準化して、REST API を記述しています。これにより、ドキュメントだけでなくクライアント SDK に使用可能な REST サービスのデータ表現に一貫性を持たせることができます。 将来的には、REST ドキュメントとサンプルの要求/応答ペイロードに対話型の機能を追加することもできるようになります。
このリリースでは、次のものが有効になりました。
新規および更新された docs.microsoft.com のエクスペリエンスに直接統合された、すべての Visual Studio ドキュメントを導入しています。
Visual Studio Hub ページには、リリース候補である Visual Studio 2017 の概要への主要なリンクが含まれています。
これには、インストール ガイド、新機能、および 作業の開始チュートリアルが含まれます。 ローカライズされたコンテンツはまもなく公開されます。 新しいコンテンツでは、リファクタリング、プロジェクトにないコードでの作業、パフォーマンスに関する問題のデバッグ、Visual Studio の起動時間の最適化に関するヒント、エディターでの新しい仕事効率化とコード ナビゲーションの機能のすべてに関する詳細、その他のトピックが利用できます。
これで Visual Studio は完全にカスタマイズ可能なインストール プロセスをサポートするようになり、お客様は使用するコンポーネントのみを取得して、個々の開発プロジェクトでどのように機能するかを詳細に参照できます。ワークロードに ASP.NET、Azure、Python、または Windows のどのプラットフォームが含まれているかは問題になりません。
ASP.NET Core と Entity Framework Core のドキュメントも、それぞれ docs.asp.net と GitHub から移行されました。
ASP.NET Core と Entity Framework Core はオープン ソース プロジェクトであるため、ソース コードとトリプル スラッシュ コメントを緊密に統合して、それぞれの API リファレンス ドキュメントを構築しました。 つまり、API とドキュメントは常に自動的に同期されます。
お客様からの長年にわたるご要望に応えて、C++ リファレンスをトピック間のリンクを少なくした、よりコンパクトな形式にリファクターしました。 これで、クラスと同じトピックでクラス メンバーのすべてのドキュメントを検索できます。
さらに、最新の C++ 標準準拠の変更と /fastlink
などの新しいビルド オプションの詳細を学び、以前のバージョンの Visual Studio からコードをアップグレードするために新しい移植ガイダンスを使用し、gcc
によって Linux システムでの構築の新しいサポートを試用する方法を検索できます。
Linux 上の SQL Server (SQL Server vNext Customer Technical Preview 1 の一部) は、ここでお試しいただけます。 [ハブ] ページには、Linux 上の SQL Server での作業の開始から管理と開発までを説明する主要なリンクが含まれています。 ローカライズされたコンテンツは近日公開されます。
当社は、さらに多くの機能を新しいドキュメント サイトに配信して、エクスペリエンスが常に製品およびサービスと一致するよう積極的に取り組んでいます。 ユーザーはドキュメント プロセスで最も重要な要素であるため、 Twitter でこのエクスペリエンスを向上させる方法について、Microsoft に問い合わせ、フィードバックをお寄せください。