なぜAWSやMicrosoftなど大企業のドキュメントは読みづらい？

大企業のライブラリやAPIのドキュメントは非常に読みづらいと思いますがどうしてなのでしょうか？
特にAWSは非常にわかりづらい。
同じ内容でも個人が書いたブログを読んだほうがよほど分かりやすいです。
MSDNなどは機械翻訳だからでしょうが、人が翻訳していると思われるものでも読みづらいです。
逆に大企業のドキュメントでも読みやすいというものはありますか？

No.3 回答者： artoo 回答日時： 2016/09/02 07:34

> 中小企業ではとっつきにくいドキュメントだと誰も使ってくれないけれど、大企業は「どうせ誰かが解説記事を書いてくれるから初心者に分かりづらくても構わない」と考えているのでしょうね。

いいえそういうことでは無いです。誰向けかと言うことで、一般ユーザー向けは正確さより分かりやすさ優先だし、技術者向けは、わかりやすさより正確さ・厳密さと言うことです。わかりやすさと、正確さ・厳密さは両立しません。中小企業が作っていても、技術者向けは正確さ・厳密さ優先でないと誰も使ってくれません。

まあ、技術者向けと、一般ユーザー向けを両方書いてくれればいいのでは？というのは言えますね。ただ、一般ユーザーというのもレベルは様々なので、「初めてプログラミングします」という人からすべてをカバーするのは無理でしょう。

No.2 回答者： artoo 回答日時： 2016/09/01 22:22

本家のドキュメントは、それが全世界のプログラマの拠り所なので、正確・厳密であることが重要であり、初心者に分かりやすいかどうかは最初から目的にしていません。

なので、初心者には分かりづらいのだと思います。
機械翻訳が読みづらいのはまた別の問題ですが。

特定の環境で特定の目的について書かれた個人のブログは、その条件が自分と合致するのであれば、役立ちます。合うのを探すのが大変ですが。
あるいは、初心者向けに書かれた解説の文章ということであれば、初心者がとっかかりをつかむのには良いかと思います。
上級者には役立たないので、本家のリファレンスを読むことになります。

この回答へのお礼

中小企業ではとっつきにくいドキュメントだと誰も使ってくれないけれど、大企業は「どうせ誰かが解説記事を書いてくれるから初心者に分かりづらくても構わない」と考えているのでしょうね。

お礼日時：2016/09/02 00:58

No.1 回答者： OnneName 回答日時： 2016/08/31 16:04

APIの仕様を完全かつ正確に記述するためですね。

コンピュータや言語に関する専門知識と読解力がないと読みづらい、解らないという結果になります。

>同じ内容でも個人が書いたブログを読んだほうがよほど分かりやすいです。
不完全かつ不正確で良いからですね。
一般的にはそれでAPIを使用する事は出来るが異常時の対処や使いこなすことは無理と言う事でしょう。

この回答へのお礼

正確さは当然としてかつ分かりやすく書くこともできると思うのですけどね。
完全さが必要なリファレンスはともかく、それが必要でないチュートリアルでも分かりづらいと思うのですよ。
例えばこのAWS OpsWorksのドキュメント
https://docs.aws.amazon.com/ja_jp/opsworks/lates …
タイトルが「AWS OpsWorks とは何ですか?」なのでOpsWorksを知らない人が最初に読むような文書だと思います。
しかしOpsWorksとは何なのか簡潔な説明が無いので、OpsWorksを知らない人がこれを読んでも分かるようにならないんじゃないでしょうか。例えAWSの他のサービスを使っていても。
一方、第三者が書いた記事はこちらです。
https://codezine.jp/article/detail/7304
「OpsWorksを用いると、短時間で手軽にアプリケーションを動かす環境一式を自動構築することができ、要件に応じて柔軟に構成を変更できます」
分かりやすくないですか。

異常時の対処といいますが、エラーの説明などは詳しく書いていなく、大体ググッてフォーラムで情報を見つけることになるんじゃないでしょうか。ある件では結局バグで数ヶ月以上放置されていました。

お礼日時：2016/09/02 01:17