少しプログラミングを覚えてきた初学者が、さらに力をつけるために必要なのが公式ドキュメントを読むことだと思います。
公式ドキュメントには、日本語の記事には書かれていないような詳細な説明や、APIの使用方法、そしてリリースノートなど、実装には不可欠な情報が掲載されています。
しかし、公式ドキュメントが上手く読めずにつまづく人も多いのではないでしょうか？慣れていない人にとっては、技術について書かれたドキュメントを読むのは難しいものです。
この記事では、つまづいてしまう人が少しでも減るように、公式ドキュメントが読めない原因と対策をいくつか書いていきます。
公式ドキュメントとは
この記事で言及している「公式ドキュメント」は、フレームワークやライブラリ、言語について、その公式組織が出している文書のことです。
具体的にはこのへん。
どうして公式ドキュメントが読めないのか
原因1. 公式ドキュメントを読む意味が感じられない
「技術的な記事はQiitaやブログにたくさん上がっているんだから、わざわざ公式ドキュメントを読む必要はないでしょ？」という気持ちです。
その気持ちもわからなくはないのですが、結局のところ、日本語で書かれた記事のほとんどが公式ドキュメントの二次情報になります。
もしかしたら誤った内容が書かれているかもしれないし、情報が古くなっているかもしれない。また、詳細なAPIの仕様だったり、各バージョンの変更点などを日本語のドキュメントで探すのは難しいでしょう。
いつまでも二次情報に頼っていたら一人前のエンジニアにはなれません。実装で困った時、自分の力で必要な情報にたどり着けるように、公式ドキュメントを読む必要があるのです。
エンジニアとして、一次情報を確認する習慣をつけていきましょう。
原因2. 英語が読めない
まあ、身もふたもない話ですが、英語が読めないので公式ドキュメントを読むのが辛い、というのが多いのではないでしょうか。
英語力を上げる、というのが1番早い解決方法なのですが、まあそれはエンジニアとしてはスマートな解決方法ではない気がします。
なので、英語が読めない場合は素直に翻訳ツールを使いましょう。さまざまなブラウザ拡張ツールが用意されていますので、お好みでどうぞ。
DeepLのChrome拡張機能
Google翻訳 - for Google Chrome
Google Translator for Firefox
これらを使えば、公式ドキュメントの画面を見ながらすぐに翻訳を見ることができるので、手間が大きく省けます。
※Google Chromeの拡張機能を使った場合
英語部分をハイライトするだけで、単語でも文章でも吹き出しに翻訳が出てくれるため、心理的な負担も減らせるのではないでしょうか。
公式ドキュメントの文章は、誰にでもわかりやすいようにシンプルな英語で書かれていることが多いので、比較的正確な翻訳がされると思います。
まずは翻訳ツールを使って、日本語に置き換えた内容を読むようしていくのが良いでしょう。
原因3. 全体像を理解していない
ドキュメントを読む前に、その言語・フレームワーク・ライブラリがなぜ作られたのか、何をするものなのか、をざっくり知っていると理解が早くなります。
例えば、reactでできることや、使った時のメリットなどについては、わかりやすくまとめられた日本語の記事が多くあります。
このような記事を参考にして、概要を知ったり、手を動かしたりしてなんとなく感覚を掴んでから公式ドキュメントを読むと、「ああ、そういうことね。」と実感を持って理解することができると思います。
いきなり公式ドキュメントを読んでみて概念がわからなかった時は、日本語でまとめてくれている資料も参考にしながら、少しずつ理解を深めていきましょう。
※日本語ドキュメントだけで良い、というわけでは決してありません。あくまでもこういった情報は公式ドキュメントをわかりやすく理解するためのもので、これらの土台をもとに公式ドキュメントを読んでいくことが大事だと考えています。
原因4. 公式ドキュメントを読む時間がない
最初のうちは、公式ドキュメントを読むのにとても時間がかかります。仕事などで時間に追われている場合には、なかなか手が回らずに日本語の記事の情報をコピペして済ませてしまうこともあるでしょう。
ただ、それでは個人のスキルは上がっていきません。もしかしたら、間違った知識を持ったまま仕事をすることになってしまいます。
まずは、しっかりと言語・フレームワークにキャッチアップするための時間を取ることが大事。場合によっては、「ドキュメントを読む」というタスクを設定してもらっても良いでしょう。
真面目な人ほど、「のんびり公式ドキュメントを読むよりも、さっさと実装して成果を出さなきゃ！」と思ってしまうかもしれません。ですが、しっかりとした知識を身につけることで、遠い目で見て多くの時間を節約することができます。
以下の記事にもあるように、「例」による理解に頼るのではなく、しっかりと「定義」での理解をすることが大事だと思います。
目先の成果だけでなく、長期的な生産性を考えながら、公式ドキュメントの理解を日々の業務に取り入れてみてください。
原因5. 公式ドキュメントを読む文化がない
ここまでは、個人レベルでの課題でしたが、同様にチームにも課題があるかと思います。
そもそもチームとして公式ドキュメントを読む文化がなければ、ドキュメントを読むタスクを作ることは難しいでしょう。
まずは、以下のような記事を読んで、公式ドキュメントを読むことの価値を共有すること。
公式ドキュメント読めば5分で解決することで5時間もGoogleとにらめっこするな - note
えふしんに聞く「僕が若手エンジニアならこれを学ぶ！」トップランナーの考える成長戦略 - エンジニア Hub
その上で、
- 公式ドキュメントを読み合わせる勉強会
- 公式ドキュメントに載っているコードをライブコーディングする勉強会
- メンターと読み合わせをして理解を共有していくペアリーディング
などを行っていけると、次第に文化が根付いてきて、チーム全体としても強くなっていくのではないでしょうか。
こういった活動は、すぐに目に見えるような効果が現れないかもしれないですが、まずは習慣を根付かせることが大事ですので、最初のうちは根気強くやってみましょう。
追記 原因6.公式ドキュメントが読ませる目的で書かれていない
Twitterやはてなブックマークのコメントなどでたくさんご指摘いただいたので追記。
フレームワーク・ライブラリによっては、公式ドキュメントが読ませる目的で書かれていなかったり、書かれている情報に不足が多かったりするものもあります。
その場合は、公式ドキュメントに頼っても仕方がありません。その場合には、「Githubでリポジトリのissueを参照する」、「リポジトリのコードを直接参照する」など自力で解決していくことが求められます。
利用者が多いリポジトリであれば、同じような課題に当たっている人がいるはずなので、issueが存在している可能性は高いですが、そうでない場合は難しいかもしれないですね。コードを直接参照して解決するのもハードルが高い。
この場合には、ブログや日本語の記事を読むしかなさそうです。解決になっていなくてごめんなさい。
ただし、近年ではドキュメントが豊富なものが増えてきています。特にVue.jsは、公式ドキュメントの読みやすさゆえに普及したとも言えるでしょう。日本語にも対応していますし。
開発が盛んなフレームワークはドキュメントもしっかりしています。技術選定の際には、「公式ドキュメントが整っているか」という観点も入れてみてください。
公式ドキュメントで殴られないために
以前の記事で、「新人を公式ドキュメントで殴ると致命傷」という内容を書いたところ、たくさんのコメントをいただきました。
公式ドキュメントを読むように促すのは良いことだと思うのですが、なぜか新人はそれが読めずに苦しんでいる。そんなギャップを埋めるために、この記事を書きました。
新人のみなさんには、この記事を参考にして、公式ドキュメントを読むのが辛い理由を明確にしつつ、その対策を立ててもらえればと思います。
また、レビュワーのみなさんには、公式ドキュメントを投げて終わりにするのではなくて、新人がどこで苦しんでいるのかを、この記事を参考にしながら考えていただけると嬉しいです。
公式ドキュメントを使いこなして、世界に引けを取らないような強いエンジニアになりましょう。