ブログの下書きを眺めてたら長文がみつかったので供養しておきます。

「まず公式サイトから読もうよ」って言い続けてたら、数年越しで結果的にその方が効率いいって気づいてくれた人もいるので、言い続けるのも大事だなーと思った。最近。
— irof (@irof) 2018年3月3日

開発では、何かを調べることに多くの時間が費やされます。私の調べ物のやりかたや、他の人のを見て思っていることを書いてみます。

前提条件

調べ物が苦手
何か効率が悪い気がする
調べ物に時間がかかる
間違った情報に振り回されている
情報が間違っているのかやり方が間違っているのかわからない

と言った方には役に立つかもしれません。自分で調べ物ができるかた、そのやり方に疑問のない方には何の足しにもなりません。あと私のやり方と、私から見える人の私からの見え方でしかないので、他のコンテキストは知りません。

また、ここでの「調べる」は初めて使用するツールの使い方など、未知領域の課題解決を行うためにインターネット等を検索することを指します。実際は検索する前に意識/無意識にかかわらず課題の切り分けを行い、問題領域によって手段を変えているはずです。

調べ物のレベル

レベル感をふわっと書いてみます。

何を調べたらいいかわからない
- 何がわからないかわからない、どう言うキーワードで調べればいいかわからない。思ったものが全く出てこず、解決しない。稀に何とかなったりするけれど、ほんと稀。
検索上位にでてきたものをそのまま試す
- 短時間でたどり着くこともあるが、打率は低い。動かないときは「調べた通りにやったけれど、なぜか動かなかった。」でゲームセット。
検索で出てきたものを手当たり次第に試す
- うまくいかないときは永久にたどり着かないが、当人は「いつかたどり着く」と思っていたりする。そのため「時間が足りない」と言うが、どれくらい時間があればたどり着くかの予想もできない。
検索結果をさらに自分の条件に照らし合わせてフィルタリングして試す
- それなりの精度と質で解決できたりする。しかしなぜそれでいいかの説明ができることは稀。「出典はWikipedia」程度の信頼性。
公式ドキュメントの手順に従う
- ドキュメントのGettingStartedなど、手順的なドキュメントがなければお手上げだったりする。
公式ドキュメントから設定を理解した上で調整する
- だいたいの問題はクリアできる。逃れられない問題として、ドキュメントの質に依存する。記載されている箇所が見つけにくかったり、そもそもドキュメントが使い物にならないプロダクトも稀によくある。
ソースコードを当たって解決する
- （コードが使える場合）解決できる問題なら解決できないほうがおかしくなる。しかしドキュメントされていないトリッキーな解決をしてしまう可能性もある。機能を損傷したり、片手落ちな設定をしてしまったりすることもある。
コンセプトを踏まえて解決する
- 「こういうコンセプトで作られているから」から導かれる解決。「そう言うことに使うものではない」と捨てる判断も早い。ドキュメントはもちろん、経験や歴史を把握していると可能になる。かもしれない。
サポートに問い合わせる
- 金の弾丸。サポートの人に教えることになることになったり、言う通りにしたら環境が壊れたとかも稀によくあるので、万能ではない。

だいたい前段階はクリアしているので、その手段でなくても前段で解決できたりします。分水嶺は5、公式ドキュメントを読めるか。これが冒頭のツイートのラインです。4までくればそれなりの精度と質で解決できてしまうので、その辺りで満足してしまっているのも多そうな感じがしています。

Qiitaが一部の人に嫌われる理由

特定サービスを出して申し訳ない。別にQiitaに限ったことではありませんが、検索時に

Qiita出てきたらまずURLで誰かいたか識別して、それから内容読むか決めるなー
— irof (@irof) 2017年4月16日

調べ物をしている人を見ていると、高確率でQiitaを参照しています。検索上位にくるのはサービスの努力も大きいでしょうが、同様の問題で困った方が書いていたりするので、近い語彙なのでヒットしやすいと言うのもあるのかなと思います。

Qiitaの記事が玉石混交であると言う事実はありますが、それは他のQAサービスやブログ、情報サイトでも変わりません。なので問題点はそこではなく レイアウトが統一されていることによる区別のつきづらさ に由来すると思います。これは「ソースはWikipedia」と言うのが揶揄の対象となるのと近いのですが、Qiitaも同様に「Qiitaに載ってた」と言うような場合に問題になります。つまり、記事の質は個人に由来するサービスの特性に対して、情報を判定する精度が個人に由来していないのです。

私も調べ物でQiitaを参照することは多いので、非常に助けられています。なので「Qiitaを見てはいけない」とまで言うつもりはないです。ちなみに、私がQiitaを参照するときは「誰が書いているか」を気にしていることが多いです。

Qiitaのコンセプトを確認してみる

qiita.com

公式ドキュメントを見るべき理由

解決したときの根拠の説明ができるかが重要です。もし解決しても、なぜそれでいいのかを説明できないのであれば、それは「たまたま」でしかありません。対面していた問題は「たまたま」で解決しちゃっていいものでしょうか。再発した場合に何か対処法はあるでしょうか。他のところに影響は与えないでしょうか。などなどあります。公式ドキュメントに記載のある方法ならば、注意すべきことがあるならば記載されていることも多いです。

また、解決できない場合もドキュメントに記載がないのであれば、ある程度「仕方ない」と思えます。そう言うものを使っていると言う事実を受け止めましょう。「ドキュメントが使い物にならないもの」とわかって使うならば、アプローチの仕方も変わってきます。その判断のためにもドキュメントを参照するべきなのです。

もし、ドキュメントに記載されている通りにやってうまくいかないのであれば、バグの可能性もあります。課題管理システムにアクセスできるなら、課題登録されていないかを検索してみましょう。次バージョンのリリースノートに載っているかもしれません。ともかく、記載の通りにやっているのに動かないのであればサポート問い合わせを検討するのがいいでしょう。OSSなら「Use the Soruce, Luke」もありです。

もう一つの理由は、互換性です。ドキュメントに記載されているものは互換性が保たれる可能性が高いです。ソフトウェアはバージョンアップするものなので、互換性は重要です。ドキュメントされているものは、バージョンアップの方法もドキュメントされることが期待できます。ソースコードから得たトリッキーな解、たとえば内部APIを触ったものなどに互換性は期待できません。更新コストを抑えるためにも、提供元が予想できる使い方をすることは重要なのです。

常に公式ドキュメントを読むか

まあこんなこと言ってる私も、つい昨日公式サイトまともに読まず「わっかんねww」とか言ってたりする。
— irof (@irof) 2018年3月3日

そうとも限りません。ブログやQiita、StackOverflowなどが検索上位に現れることも多くあります。これを除外するフィルタリングを常に検索エンジンで行うのは骨でしょうし、私はやったことはありません。

公式ドキュメントはピンポイントで私の問題に答えてくれるものではないため、（その瞬間に限って言えば）多くのノイズを含みます。常に公式ドキュメントだけを参照するのは時間がかかります。無限に時間があるならそれでもいいかもしれませんが、私の時間は無限ではないのです。そのため解決したい問題の性質によっては、公式ドキュメントを当たらないこともあります。

前段で「たまたま」と言いましたが、たまたまも悪いものではありません。公式ドキュメントではないにせよ同等の信頼性があると判断できる場合だとか、明確な検証方法がある場合だとか、まあ色々言えますが、ともかく。たまたまで解決できていい問題は、たまたまで解決してしまっても良いのです。ドツボにはまりそうになったら、落ち着いて公式ドキュメントを読めばよいだけです。

私の調べ方

アクセスしやすい公式ドキュメントを参照する
- Javadocコメントなどに記載されているものであれば、高精度な情報に最速でアクセスできる。検索する必要もない。
検索結果に一通り目を通す
- タイトルだけでも。だいたいGoogle検索結果の1ページだけで、たまに2ページ目もみる。
信頼性の高い情報を試す
- （後述）
信頼性の高い情報で得たキーワードで公式ドキュメントを検索する
- 最初から全部舐めるのは厳しいので。