仕事柄、Azureのドキュメントを結構眺めているんですが、日本語ドキュメントが日本語的に読みづらい事が結構あります。
内部で一気に機械翻訳しているっぽいのでこうなるのは理解出来なくはないんですが・・・
docs.microsoft.comはGitHubで管理されてる
実はdocsは全部GitHubで管理されてて、GitHubのリポジトリからビルドしています。
このリポジトリにプルリクエストを投げると、翻訳の提案をすることが出来ます。
プルリクしてみた
普段眺めるdocsなので、出来る事ならこちらから提案をしていきたいものです。また、不満があるなら自分からもアクションを起こすべきです。
というわけで、プルリクを投げてみることにします。今回は、「チュートリアル: Azure Kubernetes Service (AKS) 用のアプリケーションの準備」をターゲットにします。序盤の文章で、
https://docs.microsoft.com/ja-jp/azure/aks/tutorial-kubernetes-prepare-app
このチュートリアルは、7 つあるうちの 1 番目で、複数コンテナー アプリケーションを Kubernetes で使用する準備をします。 Docker Compose などの既存の開発ツールは、アプリケーションをローカルでビルドしてテストするために使用されます。 学習内容は次のとおりです。
とありますが、「7 つあるうちの 1 番目で、複数コンテナー アプリケーションを Kubernetes で使用する準備をします」というのは日本語的に不自然です。ちなみに英語では
In this tutorial, part one of seven, a multi-container application is prepared for use in Kubernetes. Existing development tools such as Docker Compose are used to locally build and test an application.
https://docs.microsoft.com/ja-jp/azure/aks/tutorial-kubernetes-prepare-app
と書かれています。翻訳自体はあっているように見えます。つまり、修正前の日本語の意味を損なわないように修正をすれば大丈夫です。つまり、
- チュートリアルは7つに分かれている
- このセクションは最初(1つめ)である
という事が明示できればOKです。これを私なりに自然な文章にすると、こうなりました。
このチュートリアルは7つのセクションに分かれており、この最初セクションでは複数のコンテナーアプリケーションをKubernetesで使用する準備をします。
https://github.com/MicrosoftDocs/azure-docs.ja-jp/pull/1280/commits/c26971596a723146ec5b50e5bb4189008753bdd4
実際にプルリクエストをする際は、docsの右上の「編集」をクリックするとGitHubの該当ソースに飛べます。ブラウザ上で編集してプルリクエストを投げられるので便利。
プルリクエストを投げると、大体1日～2日ぐらいでMSの中の人から返信が来て、マージされるかリジェクトされるかします。他に自分で投げたプルリクエストの場合、こんな感じでレスポンスが来ます。
同じく日本語的に不自然で読みづらい文章に対して修正提案をしていますが、こんな感じでマージされます。
すぐには反映されないのですが、次のリリースあたりで反映されるっぽいです。
問題があるなら提案する
docsを読んでて問題を感じたなら、そのままにしないで是非修正提案をしてみてください。ユーザー側から積極的にアクションをしていくことで、docsもよりよい物になると思います。
