Zenn
🌊

Microsoft Docsを更新してみる（Azure編）

2021/11/01に公開
Azure
document
Microsoft
idea

はじめに

Azureを利用していると、公式ドキュメントを見ることってたくさんありますよね。
ですが、クラウドになってサービス側の開発スピードが上がったことによる弊害なのか、公式ドキュメントが間違っていることも残念ながら散見されます。

また、基本的に英語でドキュメントが公開された後、機械翻訳でローカライズされることから、日本語になることで、意味が分からなくなることがあります…

（例えば、私が最近泣かされたドキュメント。呼び出Graph!と言われても…）

さて一方で、MicrosoftがGitHubを買収して3年ほど経ちました。そのせいなのか、MSの公式ドキュメントの多くは現在Githubで管理されています。せっかくGithub管理になっていて、「誰でも手軽に（？）」プルリクエストができるようになっていますので、やり方を紹介したいと思います。

なお、Microsoftアカウントすら必要ありませんが、GitHubのアカウントは必要です。

更新方法

更新方法はとても簡単で、GUIだけでもできます。

  • 公式ドキュメントの右肩の部分に[編集]というボタンがあります。押下します。

  • github上の、当該ドキュメントに飛ばされます（mdファイルで作成されるのが基本のようです）。編集ボタンを押下します

  • githubにサインインするよう求められます。

  • GUIで直していきます。今回は、とあるAzurePolicyのページで、「effect」というPropertyの説明をしているところで、本来は英単語のママで入れるのが自然な箇所が何故か翻訳されてしまっているのを直します

  • 保存時に下の枠に記入します。多分Commit messageあたりに入るんじゃないかと思われます

    ※ちゃんと見てないわけですが、内容さえ正しければ雑に行っても多分大丈夫…

  • プルリクエストを出します。更新した内容を書きましょう。他の人のプルリクエストなどを見ると「fix typo」なんてレベルから気軽に出しているようです。

なお、「提案を送信するための役立つ情報」以下の文章は勝手に追加されています。

日本語記事に対して修正を加えようとすると、ローカライズルール（日本語版）が提示されるのですが、言葉の選び方など、意外と気を使ってるんだなぁと勉強になります。

  • あとはプルリクエストが承認・マージされるのを待つだけです。修正規模や、Microsoftの中の人の忙しさ次第だと思いますが、早ければ1週間くらいでマージされるようです。試しにやった時は一ヵ月くらいで取り込まれましたので、気長に待ってみましょう。

実際にやってみた

1件、試しに更新してみました。対象ドキュメントはコチラ（Azure Policy とは）
元の文章は下記の通り。「変更前（後）にリソースを変更する」って…トートロジーというか何というか。

元の英語を見ると、「Alter」「Change」で使い分けられていました。
「リソースをデプロイ（変更）する前に、パラメータをチェックして正しい設定に修正する」…というニュアンスが全く表現できていませんので、訳を修正してみます。

もっといい単語があるような気もしますが、ダメならrejectされるだけだと思って「改める」で出してみました。（思いついた方はぜひ、さらに更新していただければと。）

結果、1か月ほど待っていると、無事に取り込まれ、contributorsにアイコンが出てきました！

（ただ、ドキュメントページ側に反映されない…時間の問題…？）

ドキュメントの種別

公式ドキュメントを「更新」観点で眺めていると、3パターンありそうなことが見えています。

  • [編集]ボタンが押せてプルリクエストを出せるページ

→上の例に書いたようにやれば、個人でも更新ができます。

  • [編集]ボタンを押すと、遷移先のGithubページが404になっているページ（おそらく、日本語訳が公開されておらず、機械翻訳Onlyで運用されているページ）

例）https://docs.microsoft.com/ja-jp/graph/migrate-azure-ad-graph-authentication-library
→一番上で例に出したページです。呼び出Graphが直せまGraph！

  • [編集]ボタンが表示されておらず、[Feedback]ボタンが有効になっている

例）https://docs.microsoft.com/en-us/security/benchmark/azure/baselines/sql-database-security-baseline
→どういうルールかはよくわかりませんが、Feedbackのみ許されているページがあります。こうなると、更新権限のあるどこかの誰かに託すしかなくなります。
試してみたこともあるのですが、3か月ほど放置されており…果たして取り込まれるのでしょうか…？

今回のように更新できないパターンもあるのですが、その場合はFeedbackしてください！というのが基本方針のようです。

おわりに

公式ドキュメントの記載がイマイチで、サポートに問い合わせた結果、載ってませんね」「間違ってますね」…ってなることがままあると思います。そんなとき、次にそのドキュメントを見る人のために、ぜひ修正してみましょう！

Discussion