Microsoft Docs の歩き方

Slide 1

Slide 1 text

Slide 2

Slide 2 text

Slide 3

Slide 3 text

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 の方と統合された ◼ 特に決まった読み方はないが、伝わればよい

Slide 4

Slide 4 text

Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. そもそもなぜ読みづらいのか 4 ◼ まぁ慣れなんだろうと思うんですが、ご意見があれば募っておこうかと思います ◼ 独自の用語がある ⁻ プリンシパル、ってよく見るけどよくわからない、とか ◼ 変に翻訳されてしまっているときがある ⁻ 右の「番号」、本来はなにか分かりますか ◼ そもそもそのサービスを触ったことがないと分からない ⁻ メニューの名前とかは触ったことがないと分からない ⁻ 当たり前のことではあるんですが、、、 https://twitter.com/kongou_ae/status/1751095402143871069/

Slide 5

Slide 5 text

Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. 英語が第一言語であることの制約 5 ◼ どうしても英語が第一に更新されるため、日本語を含むそれ以外の言語での更新は遅れる ◼ また、機械翻訳により誤って翻訳されるときもある ⁻ Microsoft docs、中でも Azure に関連する部分は人力での翻訳もかなり多いがそれでも誤りは仕方がない ◼ 最新の情報を得たい場合には英語の docs を表示させる ⁻ そのまま読む or ブラウザの翻訳機能を用いて読む ◼ Google / Bing で検索して英語のページにたどり着いてもびっくりしない ⁻ 後述の手順で言語を変えて読む or そのまま読む or ブラウザの翻訳機能を用いて読む

Slide 6

Slide 6 text

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 されるときもある

Slide 7

Slide 7 text

Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. 余談: 日本は Microsoft docs が好き？ 7 ◼ ちょっとした文化差なのかもしれないが、日本のユーザからの Microsoft docs 閲覧数は結構あるらしい ◼ 何かのサービス・プロダクトについて、操作を試してみて「こう動けばこれが仕様なんだろう」と考えるか「docs に書いてないからこの動作が仕様なのかどうかわからない」と考えるか ⁻ 書かれていないがそのように動作していて、その動作が仕様なのか確定させたい場合、英語の docs に対して GitHub 上で pull-request を投げる、というやり方 (?) がある ◼ ポリシーとして、Microsoft docs に明記されていれば基本的には仕様であり、そこから外れた使い方をしている場合には非サポートとなってしまうケースがほとんど

Slide 8

Slide 8 text

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 配下にある ⁻ コストを見るときくらいしか見ないかも

Slide 9

Slide 9 text

Slide 10

Slide 10 text

Slide 11

Slide 11 text

Copyright (C) ProGrive Consulting Co.,Ltd. All rights reserved. Microsoft docs の章・節 11 ◼ 左の縦の部分は、本のように章・節に分かれている ⁻ 章 概要、クイックスタート、チュートリアル、概念、操作方法ガイドなどは大体のサービスで書かれている 大体の内容を概要でとらえつつ、とりあえずクイックスタートで作ってみてから考えるのが多い ⁻ 節 概念の下の節ではかなり細かい内容について記述されていることが多い 特に FAQ については知見の宝庫であり、Microsoft の資格試験でも閲覧不可となっている • 「～という操作をしたらどうなるんだろう」がいっぱい書いてある

Slide 12

Slide 12 text

Slide 13

Slide 13 text

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/ が無いと、たぶんブラウザの言語設定を見ていい感じに飛んでいく

Slide 14

Slide 14 text

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 に ↑ の内容を入れる

Slide 15

Slide 15 text

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