公式ドキュメントを攻略するための手引き
はじめに
少しプログラミングを理解した初心者が、さらにスキルを高めるために公式ドキュメントを読むことがよくあるだろう。公式ドキュメントには、日本語の記事には書かれていないような詳細な説明や、APIの使い方、リリースノート等実装するのに必須な情報がたくさんある。
公式ドキュメントはOSS(オープンソースソフトウェア)において、ソースコードと双璧をなす最も信頼できる資料の１つである。ソースコードが公開されていない場合、公式ドキュメントが最も信頼できる資料になるだろう。
公式ドキュメントが必要な理由
結論、プログラマーが開発を進める際には公式ドキュメントを優先して確認するべきである。主な理由は以下の通り。
- 信頼性：公式ドキュメントには必ず正しいことが書かれている。うまく動かないプログラムがあっても公式ドキュメントを調べたら必ず正解にたどり着ける。
- 情報の網羅性：公式ドキュメントには必ず全ての情報が網羅されている。
- 公式が推奨する実装方法とサンプルの宝庫：公式ドキュメントには、動作が確認されているサンプルコードが掲載されている。実装方法を正しく学べる。
公式ドキュメントが読めない原因＆その解決策
前述で公式ドキュメントが開発業務に必要な理由を簡潔に解説したが、公式ドキュメントを上手に読めないプログラマーは少なくない。あくまで個人の主観になるが、主な理由は以下の通りである。
- 公式ドキュメントを読む意味が感じられない
- 英語が読めない
- 全体像を理解していない
- 公式ドキュメントを読む時間がない
それぞれの理由とその解決策を順番に解説する。
原因I：公式ドキュメントを読む意味が感じられない
公式ドキュメントを使うことに対する反論として、例えば以下のようなことが挙げられる。
技術的な記事はQiitaやブログにたくさん上がっているんだから、わざわざ公式ドキュメントを読む必要はないでしょ？
たしかに上の意見には一理ある。しかしながら、日本語で書かれた記事の大半は公式ドキュメントの二次情報になることは前提として理解しておかなければならない。もしかしたら情報そのものが間違っているかもしれないし、情報が古くなっているかもしれないのだ。
さらに、詳細なプログラムの仕様や各バージョンの変更点などを日本語の情報で探すのは難しい。ほとんどの公式ドキュメントは英語で書かれているからだ。プログラマーとして円滑に実装を進めていくには、一次情報を確認する習慣をつけることが重要になる。Google検索で得られる二次情報に頼りすぎない。
原因II：英語が読めない
公式ドキュメントが読めない原因の１つに、英語が読めないから公式ドキュメントを読めないことが多いのではないだろうか？
英語力を上げるのが最も早い解決方法であるものの、英語力には個人差があるのであまり良い解決策とはいえない。英語が読めない場合は翻訳ツールを使おう。
おすすめの拡張機能は以下の通り。
これらを使えば、公式ドキュメントの画面を見ながらすぐに翻訳を確認できる。英語がどうしても苦手ならぜひ実践しておきたい。公式ドキュメントの文章は誰でも理解できるように、高校1年レベルの英語で書かれていることが多いので比較的性格な翻訳がなされるだろう。
原因III：全体像を理解していない
ドキュメントを読む前に、その言語、フレームワークやライブラリが作られた背景をザックリ理解していると内容が頭に入りやすいだろう。まずは日本語でわかりやすく解説されている記事を参考にして全体感を把握することから始めよう。
公式ドキュメントを読んでわからないことが出た場合は、日本語の記事や資料を参考にしながら理解を深めるといいだろう。
原因IV：公式ドキュメントを読む時間がない
最初のうちは、公式ドキュメントを読むのに時間がかかるだろう。時間に負われている場合は、なかなか手が回らずに日本語の記事の情報をそのままコピペして済ますことがよくあるだろう。しかし、そのままではスキルは上がらない。
まずは、言語やフレームワークそのものを理解するための時間を十分に取ることが非常に重要である。公式ドキュメントを読むことをタスクとして設定するのもありだ。公式ドキュメントで体系的な知識をみにつけることで理解が深まり、多くの時間を節約することにつながる。
目先の成果や時間ではなく、長期的な生産性を考慮しながら公式ドキュメントの理解を深めることが非常に重要だ。
公式ドキュメントの注意点
ここまで公式ドキュメントの利点や解決策を紹介した。しかしながら、公式ドキュメントは万能ではない。
ドキュメントは古くなりがち
公式ドキュメントの中には、情報が長い間更新されていないせいで性格ではない情報が少なくない。これは二次情報にも通じる。このようなときにできることとして、Masaki HaraのZenn記事では以下のように述べられている。
こんなとき、あなたに出来ることがもう1つあります。古くなった公式ドキュメントを書き換えて新しくすることです。これは非常に重要な貢献です。これをできるのは、実際に手を動かして問題に気付いたプログラマーだけです。そして、同じ部分を参照する人を救うのですから、これは立派に意義があることです。
上述の引用からわかることは、ドキュメントの中にある古くなった情報を新しい情報に書き換えることが解決策の一つとして挙げられていることだ。公式ドキュメントの誤りを訂正することは、同じ公式ドキュメントを使っているプログラマーやそのコミュニティに貢献するので大いに意義がある。
「組み合わせ」に弱い
公式ドキュメントがライブラリの掛け算に対応していないわけではないものの、2つの異なるライブラリやソフトウェア(例えばPythonとNoSQL、FlutterとLaravelなど)の組み合わせに関する情報は公式ドキュメントについて書かれていないことがある。
このような場合、困っている人がいればそのような情報は助けになる可能性が高い。
問題からの逆引きが難しい
書いたコードに問題がある場合、実際に公式ドキュメントが直接助けになることは非常に稀である。理由は以下の通り。
- 問題はライブラリと環境の組み合わせの一例として生じるものが大半で、特定のドキュメントだけで網羅しきれる内容ではないから。
- 問題解決に重要なことは解決するためのヒントを得ることであり、情報の信頼性はそこまで重要ではない。
何らかの問題が発生したとき、まっさきにやるべきことは次の2つである。
- Google検索を使う
- StackOverflowで質問を検索する
問題解決のヒントが得られたあとに、問題の原因を正確に理解するには公式ドキュメントだけではなくソースコードも確認しよう。上手に道具を使い分けて、問題解決の達人になろう。
おわりに
今回の記事では、公式ドキュメントを攻略するための手引きを以下の観点から徹底解説した。
- 公式ドキュメントが必要な理由
- 公式ドキュメントが読めない原因とその解決策
- 公式ドキュメントの注意点
公式ドキュメントは円滑に開発を進めていくためには必要不可欠な情報源である。本記事を通して、公式ドキュメントを駆使して開発の生産性を向上させるきっかけになれば幸いである。
参考サイト
Discussion