GCP ドキュメントの歩き方

apstndb commented 6 years ago

GCP のドキュメントに関するバッドノウハウみたいな話はわりと頻出なのでまとまっていると良いのかもしれない、ということで少し書いてみた。

日本語ドキュメントによくある問題

訳が適切でないことがある(今は改善されたが無料階層など)
ページ(サービス)の更新に追従できていなくて古い。下記のような致命的なものもある。
- リリースノートの項目が更新されていない
- 既に GA になったものが日本語ドキュメントだと alpha と書かれているままだったりしたことがある
- 課金体系の変更に追従していなかったりする
ドキュメント構成の変更に追従できていない
- サイドバーのドキュメント構成が古いままで、新しいドキュメントにたどり着けないことがある
  サイドバーが表示されていないのはどういう状況か
既にサイドバーに表示される目次からは削除されたドキュメントが残っていて検索などでヒットする場合がある。その際にはサイドバーが消えた状態になる。
2018年4月9日現在の例「Compute Engine への Docker コンテナのデプロイ」
- ?hl=en を指定すると「Deploying Containers on VMs and Managed Instance Groups」に飛び、更に ?hl=ja を指定すると「VM およびマネージドインスタンスグループへのコンテナのデプロイ」に飛ぶ

?hl=ja

?hl=en

言語設定の方法(下に行くほど優先度が強いため上のものを上書きする)

ブラウザの言語設定(accept-language ヘッダ)
- 全体の言語設定を英語にしたくない人は言語設定別にブラウザのプロファイルを分けるなどの手がある
ページフッタの言語設定ドロップボックス
- https://cloud.google.com/i18n/setlang/ によりセッションクッキー(例 Cookie: django_language=ja)として設定されるので、閉じると設定が消える
URL query string の hl フィールドを使うとブラウザの言語設定、 Cookie に影響されずに言語を指定できる
- 例
  - ?hl=ja
  - ?hl=en
- リンクを共有する場合は同じ言語で見えることを保証するために明示的につけると良い

ベストプラクティス

個人的には Concept, 概念 のところを一度大まかに把握したい時には日本語を参照するけど、日本語だと事実が変わっていることがあるので調査は常に英語でやっている。一般のドキュメントは末尾の最終更新日を見て、英語の最終更新日もしくはリリースノート等で確認できる機能のアップデートと比べて古くなければ問題ないと判断しても良いかも。(ただし、日本語版が元にした版はアップデートよりも古い場合がある) 2018-04-09 15 16 16

2019年6月追記

2019年5月下旬頃にページヘッダからも言語設定できるようになった。ある程度ウィンドウ幅が広くないと出てこない様子。

apstndb commented 6 years ago

日本語ドキュメントを読んでいる時に原文との最終更新日を比較してくれる銀の弾丸な Chrome 拡張「GCP outdated docs checker」がリリースされたそうです。 https://twitter.com/addsict/status/1014844334066188293

apstndb commented 5 years ago

ページヘッダからも言語設定できるようになっているのであとで更新する

apstndb commented 5 years ago

Android/iOS の Chrome でも使えるはずの hl=en を付けて URL をコピーする bookmarklet https://gist.github.com/apstndb/4d6e0b36b3f98d450bd8581ace90c4d4

gcpug / nouhau