Microsoft Docs の歩き方

社内勉強会のスライドです。
Microsoft docs (https://learn.microsoft.com/ja-jp/azure/) が見づらい、とよく言われているので、個人的な思いとか、tips とかをまとめています。

https://www.progrive.co.jp/

Transcript

1. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. https://www.progrive.co.jp Microsoft docs の歩き方
2. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. はじめに ◼ この資料を読むことで、Microsoft 公式ドキュメント群を読むのが少しは楽になることを目指します ◼ 対象は https://learn.microsoft.com/ 配下にあるドキュメントとします
3. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. 読み方 3 ◼ いくつかの読み方がある、気がする ⁻ 公式ドキュメント、公式 Docs、docs (どっくす) これは以前のドメインが https://docs.microsoft.com/ であったから 今 https://docs.microsoft.com/ にアクセスすると https://learn.microsoft.com/ に redirect される ⁻ MS Learn、Microsoft Learn (らーん) これは現在のドメインが https://learn.microsoft.com/ であることによる かつては MS Learn は 自習用コンテンツ の方であったが、docs の方と統合された ◼ 特に決まった読み方はないが、伝わればよい
4. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. そもそもなぜ読みづらいのか 4 ◼ まぁ慣れなんだろうと思うんですが、ご意見があれば募っておこうかと思います ◼ 独自の用語がある ⁻ プリンシパル、ってよく見るけどよくわからない、とか ◼ 変に翻訳されてしまっているときがある ⁻ 右の「番号」、本来はなにか分かりますか ◼ そもそもそのサービスを触ったことがないと分からない ⁻ メニューの名前とかは触ったことがないと分からない ⁻ 当たり前のことではあるんですが、、、 https://twitter.com/kongou_ae/status/1751095402143871069/
5. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. 英語が第一言語であることの制約 5 ◼ どうしても英語が第一に更新されるため、日本語を含むそれ以外の言語での更新は遅れる ◼ また、機械翻訳により誤って翻訳されるときもある ⁻ Microsoft docs、中でも Azure に関連する部分は人力での翻訳もかなり多いがそれでも誤りは仕方がない ◼ 最新の情報を得たい場合には英語の docs を表示させる ⁻ そのまま読む or ブラウザの翻訳機能を用いて読む ◼ Google / Bing で検索して英語のページにたどり着いてもびっくりしない ⁻ 後述の手順で言語を変えて読む or そのまま読む or ブラウザの翻訳機能を用いて読む
6. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. Microsoft docs は GitHub で管理されている 6 ◼ 誤りがあった場合や修正したい場合には、GitHub 上で pull-request を出すことができる ⁻ ただし英語のコンテンツのみ ⁻ 日本語のコンテンツについて、かつて GitHub 上で管理されていたこともあったが今は別の管理になっている ◼ https://github.com/MicrosoftDocs/azure-docs ⁻ article 配下に、公開されている URL と同じような階層構造で保管されている ⁻ https://learn.microsoft.com/en-us/azure/expressroute/expressroute-faqs → https://github.com/MicrosoftDocs/azure-docs/blob/main/articles/expressroute/expressroute- faqs.md ◼ 実際には、非公開の repository と併せて管理されており、 提案した pull-request が非公開側ですでに更新予定があれば thank you からの reject されるときもある
7. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. 余談: 日本は Microsoft docs が好き？ 7 ◼ ちょっとした文化差なのかもしれないが、日本のユーザからの Microsoft docs 閲覧数は結構あるらしい ◼ 何かのサービス・プロダクトについて、操作を試してみて「こう動けばこれが仕様なんだろう」と考えるか 「docs に書いてないからこの動作が仕様なのかどうかわからない」と考えるか ⁻ 書かれていないがそのように動作していて、その動作が仕様なのか確定させたい場合、 英語の docs に対して GitHub 上で pull-request を投げる、というやり方 (?) がある ◼ ポリシーとして、Microsoft docs に明記されていれば基本的には仕様であり、 そこから外れた使い方をしている場合には非サポートとなってしまうケースがほとんど
8. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. Microsoft docs のドメイン・パスなど 8 ◼ https://learn.microsoft.com/ ⁻ Microsoft docs はこの FQDN 配下にある ◼ https://learn.microsoft.com/ja-jp/azure/architecture/ ⁻ Architecture Center、アーキテクチャ パターンがいろいろ書いてあって楽しい ◼ https://learn.microsoft.com/ja-jp/azure/well-architected/ ⁻ W-AF、Well-Architected Framework ◼ https://learn.microsoft.com/ja-jp/azure/cloud-adoption-framework/ ⁻ CAF、Cloud Adoption Framework ◼ https://learn.microsoft.com/ja-jp/training/ ⁻ かつて Microsoft Learn といえばこっちを指していた、自習用コンテンツ ◼ https://azure.microsoft.com/ ⁻ 製品紹介ページっぽいものはこちらの FQDN 配下にある ⁻ コストを見るときくらいしか見ないかも
9. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. 余談: Azure VM の価格ページの見方 9 OS の種類 VM のカテゴリ VM のシリーズ VM のリージョン 表示する通貨 表示する単位 節約の選択肢
10. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. Microsoft docs の見方 10 パンくずリスト ほかの章・節へのリンク 目次
11. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. Microsoft docs の章・節 11 ◼ 左の縦の部分は、本のように章・節に分かれている ⁻ 章 概要、クイックスタート、チュートリアル、概念、操作方法ガイド などは大体のサービスで書かれている 大体の内容を 概要 でとらえつつ、とりあえず クイックスタート で作ってみてから考えるのが多い ⁻ 節 概念 の下の節ではかなり細かい内容について記述されていることが多い 特に FAQ については知見の宝庫であり、Microsoft の資格試験でも閲覧不可となっている • 「～という操作をしたらどうなるんだろう」がいっぱい書いてある
12. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. Microsoft Copilot の利用 12 ◼ Edge を使っていると、Microsoft Copilot (旧: Bing Chat for Enterprise) が使える ⁻ 長い文章を読むときに、いったん要約させてから本文を読むと読みやすいかも
13. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. tips 13 ◼ 言語の切替え ⁻ https://learn.microsoft.com/ja-jp/azure/ を https://learn.microsoft.com/en-us/azure/ に ⁻ もしくは地球のマークを押す ⁻ Microsoft docs 以外にも Microsoft のページであれば大体この tips が使える アクセシビリティとかを大事にしている企業なので、、 ◼ /ja-jp/ とか /en-us/ が無いと、たぶんブラウザの言語設定を見ていい感じに飛んでいく
14. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. tips 14 ◼ Bookmarklet にすると便利 ⁻ javascript: if (location.href.match(/((docs|azure|learn)\.microsoft\.com)\/en-us\//)) { location.href = location.href.replace(/en-us/, "ja-jp") } else if (location.href.match(/((docs|azure|learn)\.microsoft\.com)\/ja-jp\//)) { location.href = location.href.replace(/ja-jp/, "en-us") } ◼ 適当なページを開く → お気に入りにする → 編集 → URL に ↑ の内容を入れる
15. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. tips 15 ◼ AWS でいう A は Azure だと何？ ⁻ https://learn.microsoft.com/ja-jp/azure/architecture/aws-professional/services ◼ GCP でいう（ｒｙ ⁻ https://learn.microsoft.com/ja-jp/azure/architecture/gcp-professional/services
16. Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. 16 会社名 株式会社プログライブコンサルティング [ProGrive Consulting Co., Ltd.] お問い合わせ info@progrive.co.jp ~ Expand Your Business ~ ～ビジネスの成長、新たな機会の追求、そして未来を切り開く～