Microsoftのドキュメントはなぜ「わかりにくい」といわれるのか - kkamegawa's weblog

Xでも社内でもしばしば「Microsoftのドキュメントがわかりづらい」という声を聴きます。私は印刷物のころから…それこそMS-DOSの時代から、ずーっと見ていたので、慣れきってしまったのか、「わかりづらい」とはあまり思っていません。もちろん初めて聞く概念や初めて学ぶ分野（例えば認証で使う標準技術に関連するところ）に関してはわかりづらいではなく、「知らない」のとMicrosoft外の技術に関しては本来の規格の仕様書を読むのが筋です。標準規格の部分に関しては軽く書かれることもありますが、それを求めるのは酷というか、対象外でいいでしょう。 で、ここではいくつかのタイプを想定して考えてみます。対象は .NET とAzureとしてみます。ほかのドキュメントでも大して変わらないかもしれませんが、私がよく見るのがこのへんなので。 Xのような140文字で「わかりづらい」では何がわからないのかわからないの

[stabucky]

Azureとか言っている人は技術者だろう。頑張れ。問題はPower Automateみたいな初心者向けのツールの説明が致命的なこと。具体例が少ない上に、翻訳ミスなのか何なのか、そのままやっても動かないケースがほとんど。

[yuangao]

サービス名が変わる、ドキュメントにより酷い時はそのページ内でも用語の統一が徹底されないのも混乱する所。全く違う名称に変更だといいけど、既存の一部の名称を全体に拡張したり微妙に変えたりが多くて困る。

[dodecamin]

“誤訳とかは「わかりづらい」ではなくドキュメントのミスなので対象外” MSのドキュメントはとにかく致命的な誤訳が多い。

[kazuppo01]

ちゃんとしてるんだけど、情報量が多いのに、情報に優劣をつけた書き方してないから頭に入ってこないというイメージ

[dh16t]

チュートリアルをそのままやっても動かなくてハマることが多いイメージ

[applesin]

肝心のとこが書いてなかったり、たらい回しにされる感はある。ケムに巻かれるというか。

[trace22]

エンジニア側だけど情報量が多い割に必要なとこは無いイメージだわ。/追記:参照ばっかりで肝心の説明どこだよがかなりある。これは日英関係なく多い。

[sisui_ro]

左の目次というのかナビゲーションというのか、それが微妙だとずっと思っている。あと、本当に教えて欲しいことを教えてくれないことが多い。それはつまりMSがやってほしくない事だったりするわけだが…。

[usurausura]

OSやブラウザの環境、IPアドレスが日本であってもMS製品全般のオンラインヘルプの英語原文に容易にアクセスできるようにして欲しい。本当に。マジで。

[kaorun]

古いMSJJやMSDNマガジンが捨てられんのですよマジで。/まぁ、いまのMSのドキュメントは作り手側が自分の理屈を説明してるだけだからなぁ、というお気持ち

[strawberryhunter]

今は知らないけど、VBAのドキュメントはオブジェクト単位ではなく、同じ名前のメソッドでページがまとめられていた。本当にそういう内部実装だとしても謎すぎる。

[tybalt]

分かりやすいドキュメントの要件は、仕様の情報が地の文とは分かれており明快かつ簡潔かつ網羅的にまとまっている、使用例がたくさんある、の二点だと思うけど、英語の作文のお作法と相性が良くない気もする

[meganeya3]

GUI操作のHOWが知りたいところを、文字で構造解説されて俺が今欲しいのは知識ではない

[harumomo2006]

Microsoftに限らず技術的な文章はだいたいどこも分かりにくい。日本語でも分かりにくいのだから英語圏特有のウィットが含まれる文章はますます分かりにくい

[atsushieno]

日本語ドキュメントは読まないから知らないが、英語版ドキュメントが特段わかりにくいと思った印象はない（特に良いとも思っていない）ので、日本語版の問題では。/ 日本のエヴァは自分の仕事だと思ってない。

[sekiu]

わかりやすくしたらエヴァンジェリストの仕事無くなるじゃん

[l1o0]

歴史が長い・ステムが複雑・モジュール化がされてない・範囲が広いので情報量が過多。専門用語と特殊な使い方が多い。開発者・管理者・利用者のどれを想定しているのか不明確。前提知識を省略していることがある。

[Shinwiki]

ドキュメントの説明対象であるシステムの作りからして愚かだからだよ。バカが作ったもんを縦割りで別のバカが説明してんだもん。わかりやすいわけねーやな。Azureクソ滅びよ。

[yshkn]

最近マシになってきた気がするけど、めちゃめちゃ読みにくい日本語機械翻訳が多くてわかりやすいわけない印象

[tomei10]

最近はかなり分かりやすくなって来たという印象。むしろAWSのほうが分かりづらいサービスがあるぐらい。機械翻訳なのと、体系化されてないというか、ツギハギでドキュメントを追加してきたせいじゃないかな。

[secseek]

要は技術者の書いたマニュアルだからだと思います。必要な項目を列挙しただけでその理由まで言及してないとかですね。技術文書なんてそんなもんだと言ってしまえばそれまでですが

[neco22b]

MS-DOSの頃の方が読みやすかったような？紙だったけど。MSKKが作っていたし？

[t1mvverr]

ドキュメント意味分からないから無料枠で仮構築でガチャガチャしながら構築手順書作るようにしてる

[yoppema]

MSは事例が少なくて本当にわかりにくいと思う。

[togusa5]

やる気がないから

[misshiki]

“検索はたいてい「この内容が書いてあるはず」という英単語（日本語ではなく）を指定して、site:learn.microsoft.comで検索しています。”

[atsushifx]

規格の仕様書という、どちらかというと分かりにくい系統の文syなのに加えて、機械翻訳との組み合わせが最悪なんだと思う

[Goldenduck]

固有名詞である製品名を網とか訳してくるし情報が散らばりすぎ

[teramako]

。網

[circled]

検索サイトから入ると、戻るボタンを押しても検索サイトに戻れず、ずっとドキュメントのページから逃れられない仕様を何とかして欲しい。抜けられないvimじゃないんだから

[cu39]

MSに限らず原因の1つだと思うのは、冒頭近くで「【用語・概念】については【リンク】を参照してください」的な挿入があって結局どういう順序で理解すればいいかわからないやつ。

[tastystream]

Microsoft Learnにほとんどすべてのドキュメントを集約したことで、内容が有象無象と化しています。とても古いドキュメントを中途半端に消すのと、そういうドキュメントのリンクを修正することはまずないのも追加で。

[PEEE]

MSのエコシステムの連携と過去の製品や機能の積み重ねがあって、MSならその量は言わずもがな。そもそもの文量が膨大に加えて、個別記事でも経緯とか例外とかいろいろ書いておかなきゃならんことが多すぎるのよね。

[hiroshe]

Googleよりはましだと思うんだが

[crexist]

まぁ、Apple のドキュメントも昔は相当わかりづらかったよ。 そもそも説明に"this is class" とか"initializer"とかしかないものも多かった。 その点adobeのドキュメントは良く出来てたと思う