Terraform のドキュメントに比べて Google Cloud のドキュメントが読みやすいと感じた

英語レベルは TOEIC 700後半ぐらいなので人並みには読めるつもりです。

しかし Google Cloud と Terraform のドキュメントを読む時で明らかに読みやすさに差があります。いったいこの違いがどこからきているのか？について調査してみました。

実際に見てみた記事。

注意

この記事は自分がなぜ苦手なのか？を究明するための記事であり、何かを貶すつもりは一切ありません
また自分以外の何かに改善をもとめるものでもありません

そもそも用途が異なる

英語の文章ということでひとくくりにしていましたが、Google Cloud は概念の説明をしているのに対し、Terraform はツールの各パラメータの説明（リファレンス）です。

そのためそもそも細かいことや前提知識を端折って書かれているのが当たり前なので、コンテキストを読み取るのに苦労していたようです。

文体の癖

可能な限り簡潔にしようとしている Terraform のドキュメントに対して、Google Cloud では背景や注意点、他のケースではどうなるのかをストーリーで紹介してくれています。この点により、多少一文理解できなくても前後の分で補完できます。

一方で Terraform はそこが理解できないと、他の文では代用できません。

また、Terraform の文章は無生物主語が多く採用されることが多く、you という語りかけるような表現がすくなくなるため読解に慣れが必要です。

実際に同じ文章を読んでみる

AI に生成してもらいました。

Google Cloud バージョン

To ensure the load balancer directs traffic to the correct application port on your backends, you need to specify the port_name. This setting should match the name you assigned to a specific port when you configured your instance group or Network Endpoint Group (NEG).

For example, if your application containers listen on port 8080 and you named this port 'web-app' in your instance group setup, you would enter 'web-app' in the port_name field for this backend service. This tells the load balancer precisely where to send the incoming requests. If you are using an instance group and don't specify a port name, the load balancer might default to using the port named 'http'.

ロードバランサがバックエンドの正しいアプリケーションポートにトラフィックを転送するようにするには、port_name を指定する必要があります。この設定は、インスタンスグループまたはネットワークエンドポイントグループ（NEG）を構成する際に特定のポートに割り当てた名前と一致させる必要があります。

たとえば、アプリケーションコンテナがポート8080で待ち受けており、そのポートに「web-app」という名前をインスタンスグループの設定で付けた場合、バックエンドサービスの port_name フィールドにも「web-app」と入力します。これにより、ロードバランサは受信リクエストを正確に送信すべき場所を認識できます。インスタンスグループを使用していて port_name を指定しない場合、ロードバランサはデフォルトで「http」という名前のポートを使用する可能性があります。

Terraform バージョン

port_name (String, Optional) - Specifies the name of the port exposed by the backend instance group or Network Endpoint Group (NEG). Traffic is forwarded to this port. Must correspond to a named port defined on the backend resource. Defaults differ based on backend type if unspecified.

port_name（文字列型、省略可能）

バックエンドのインスタンスグループまたはネットワークエンドポイントグループ（NEG）で公開されているポートの名前を指定します。トラフィックはこのポートに転送されます。この値は、バックエンドリソースで定義された「名前付きポート」と一致している必要があります。未指定の場合は、バックエンドの種類に応じてデフォルト値が異なります。