【新人プログラマ応援】公式ドキュメントも読もう

「新人プログラマ応援 - みんなで新人を育てよう！」 というイベントが開催されているのを見つけましたので、自分もこの記事で参加しようと思います。

内容はタイトルの通り、「公式ドキュメントを読む」ことの重要性についてです。

あなただれ？

@chooyan_eng です。文系未経験からこの業界に新卒で入って今 12 年目に入りました。

新卒入社した会社に7年ほど在籍したあとフリーランスになり、今は Flutter というフレームワークを使って Android / iOS 向けのモバイルアプリ開発を主に仕事としています。

Flutter のパッケージ（ライブラリ）も開発しています。もし Flutter でのアプリ開発に興味がある方はぜひ。

その他に講師の仕事もしています。毎年春には新人研修も担当します。

本文

すでに開発の経験があるある方も、これから研修で覚える方も、「何も見ないでプログラミングをする」ということは不可能だと思います。私も無理ですし、それを目指そうとも思いません。プログラミング（というかシステム開発）に必要な知識はあまりにも膨大で、ひとりの人間の脳に全てを入れておくことは不可能だからです。

そこで、必要に応じて Web で調べる（つまり「ググる」）ことをしながら開発を進めることになるわけですが、その調べ方にもポイントがあります。それが 一次情報かどうかを確認する という点です。

一次情報とは

システム開発における一次情報とは、 その技術を開発している本人（たち）が提供するドキュメント のことです。公式ドキュメントとも呼びます。

Java にしろ Ruby にしろ Flutter にしろ、プログラミング言語やフレームワークには必ず「それを開発している人たち」が存在します。そして、その開発者たちが提供するものには技術そのものだけではなく、その技術を使う人たちのためのドキュメントも含まれます。

どのような文法で、どのようなクラスがあって、どのようなメソッドを持っていて、どれを呼び出したら何が起こるのか、といった説明がそのドキュメントには網羅されていることが多いでしょう。¹

例えば、Flutter の公式ドキュメントは以下のサイトです。

ここには Flutter とは何であるか、どのように使うのか、なぜそのような作りになっているか、今後はどのようなバージョンアップを予定しているか、開発に参加するにはどうすればよいか、などの情報がまとまっています。

また初学者向けのチュートリアルなども公式ドキュメントに載っていることが多いです。下手な入門記事を参照するよりも分かりやすく役にたつ場合も少なくありません。

いくら言語やフレームワークなどの技術を開発して公開したとしても、それをどう使えば良いのかを使う側（つまり我々開発者）が理解できなければ誰にも使ってもらえない技術になってしまいますので、基本的には技術とセットで必ず公式ドキュメントが主に Web 上で提供されます。これが一次情報です。

技術記事などの情報

一方で、ググって出てくる検索結果には、公式ドキュメント以外にも「その技術を使っている誰か」が書いた技術記事も数多く上がります。この Qiita に集まる記事も同様です。

これらの記事は目的に合わせてパッと参照しやすい、答えが見つけやすい、というメリットが往々にしてあるため、特に初学者が調べ物をする際はまずこのような記事を利用することが多いのではないかと思います。

@jnchito さんにコメントいただいた通り、公式ドキュメントなどの一次情報は想定する読者のレベル感はその技術によって様々です。

例えば Python や Ruby などのプログラミング言語の公式ドキュメントの場合、PC のメモリ管理や HTTP の仕組みなど、情報工学の基礎的な知識があることを前提に説明が進むことも少なくありませんし、Flutter などのフレームワークの公式ドキュメントで「変数とは」のような一般的なプログラミング知識の解説が詳しくされることはありません。いわゆる「プログラミング初学者」にとって、公式ドキュメントはハードルが高い場合も多いと言えるでしょう。

一方で技術記事のレベル感はそれを書いた人が自由に設定できますので、一次情報を噛み砕いて自分にあった難易度で説明してくれる技術記事を探し出せれば、その記事は自分にとって大きな助けになるはずです。

ただし、一次情報ではない技術記事は、その書き手の事情として以下の点を考慮しておく必要があります。

• 書き手は「その技術を開発した人」ではないため、その技術の全てを把握しているわけではない。²
• その記事の内容が正確であることを保証する必要がない。（誤った情報を発信することによる不利益がほとんどない）
• 技術のアップデートによってその記事の内容が古くなったとしても、それを修正する義務がない。（放置することによる不利益がほとんどない）

特に「不利益がない」という点は個人的にとても重要だと考えています。

一次情報を提供する立場の場合は、ドキュメントに誤りが含まれたり情報が古くなることなどによる品質の低下は「その技術の利用者が減る」という不利益に直結します。そのため、品質が高い状態での一次情報の提供は技術の開発側の視点としてはとても重要で優先度の高いものです。

しかし一方で、技術記事の書き手としては、その記事に誤りが含まれたり古い情報が残っていたりしたとしても、せいぜいコメント欄で批判されたりフォロー者数が減ったりする程度です。むしろ「記事を書いてアウトプットしている」という点ですでに一定の評価を得られるため、プラスマイナスで言うとプラスの場合も少なくないでしょう。

言い換えると、記事の品質を高めるインセンティブが（一次情報に比べて）あまりない、ということです。

技術記事を読んで参考にする場合は、必ず技術記事のこのような特性を頭に入れた上で、技術記事と公式ドキュメントの適切な使い分け考える必要があるでしょう。

まとめ

まとめると、公式ドキュメントとそれ以外の技術記事には、それぞれ以下のようなメリット・デメリットが存在します。

メリット

• 一次情報
  • 情報の網羅性、正確性がある程度保証されている。
  • その技術がそのような作りになった背景も書かれている場合が多い
  • どのような仕組みでそのように動作するのかが書かれている場合も多い
  • 技術のアップデートがあればリアルタイムにそれが反映される
  • その技術についての深い理解が得られる
  • とにかく利用者の利益になるように情報が整備される
• 技術記事など
  • 公開されている 情報の総量が圧倒的に多い
  • 今知りたい内容にピンポイントですぐにアクセスできる
  • （日本人にとっては）日本語で情報を得られる

デメリット

• 一次情報
  • 特定の状況に合わせた説明ではないため、「だから自分はどう使えば良いのか」は自分で考える必要がある。
  • 内容を理解して自分のコードに反映するまでに時間がかかる
  • 日本語訳されていない場合も多い
• 技術記事など
  • 情報の質については何も保証されない。
  • 誤った内容が含まれる可能性が（一次情報に比べて）高い。
  • 書き手の思想などにより内容に偏りが含まれる場合がる。

ざっくりまとめると、 品質の高いソフトウェア開発には不可欠な内容だけど読んで理解するのに時間がかかる のが公式ドキュメント、 さっと調べてすぐに使えるけどそれが良い解決策なのかは分からない のが技術記事などその他の情報であると言えるでしょう。

このことをおさえた上で、調べ物をする際は必ず一次情報である公式ドキュメントも読むようにすると良いと考えています。

個人的なオススメは 技術記事で当たりをつけて、公式ドキュメントで正確に理解する というやり方です。技術記事である程度の当たりをつけた上で公式ドキュメントも一緒に読んでみることで、正確で深い理解を効率的に得る、という方法です。

公式ドキュメントも読むことで、もしかしたらその技術記事が触れていない注意点やよりよいクラス・メソッドが見つかるかもしれませんし、なぜそのような作りになっているかの背景も知ることができるかもしれません。そしてそれらの知識は、今後別の問題が出てきた時でもある程度のあたりをつけるための知識になるでしょう。

技術記事に載っているコードをコピペして動いたことを喜ぶのは趣味だけにとどめておいて、時間のとれる限り公式ドキュメントに目を通し、より深くより正確な理解を得ることがその後の開発者としての成長にも役立つでしょう。

1. 「でしょう」というのは、ドキュメントもやはり人が作るものである以上、抜け漏れやコスト的な制約による「書ききれない部分」が存在し、必ずしも「網羅されている」ことが保証されているわけではない、というニュアンスです。その度合いはそれぞれの技術の開発体制によって異なりますので、技術そのものの使い方だけでなく、どのような状況でその技術が開発されているかに興味を持つことは大切です。 ↩

2. もちろん書き手によってはその技術についてとてもよく精通していて、公式ドキュメントとはまた違った切り口から読み手にとって有益な情報を発信してくれる場合もたくさんあります。どの筆者のどの記事がそのような有益な記事なのかを判断できるようになるのも、開発者としてのスキルのひとつと言えます。 ↩