とある日常
コードレビューで一度くらい指摘されたことはないでしょうか?
公式ドキュメントに使い方載っているので、それを参考にして修正してください
公式ドキュメントではそう書いていないはずです
時には、コードに関する質問をしたとき
これ読めばわかるよ。はいっ(公式ドキュメントのURI)
そんな時、どう思いました?
僕)
「読めって言われても...」
「読んでも結局何が言いたいか分からない...」
「英語のドキュメント読むのきついなぁ...」
「ChatGPTに使い方全部聞いたれ」
そう思ったことはないでしょうか?
まずドキュメントは読めるべきなのか
べき論になると、当然読めた方がいいに決まっています。
ただ、新人のうちから読める必要はないと思っています。
必要な情報をピンポイントで早く見つけるには一定の経験が必要なので、最初に読めないことで落ち込むことはない思います。
といっても、読める方がいいのです。
それなりに信頼できる
公式ドキュメントは、作者か作者の意図を理解している人が執筆しているので、ある程度の信頼性があると思っています。また、更新の早いライブラリの最新情報はAIに聞いても、古めな返答が返ってくることがあるので、公式ドキュメントで最新の情報をキャッチアップしたいです。
(ドキュメントによってはメンテされていないこともあるので一概に言えないのが辛いところ)
公式の書き方を学べる
公式ドキュメントには大体「Get Start」の項目とサンプルコードを用意してくれています。ちょっとした実装方法やコードの書き方のお作法を学び取れます。
自分は複数通りの書き方があった時、公式ドキュメントのサンプルを参考にすることが多いです。
網羅的に学べる
ライブラリのドキュメントなら、そのライブラリのオプションの一覧や他ライブラリとのコラボレーション方法なども掲載しています。
こういった網羅的な情報はQiitaなどの記事よりも、優れています。
※余談
Next.js のようなコミュニティの大きなフレームワークでは、ドキュメントが非常に充実しています。自分は技術選定の基準として、「ドキュメントが充実している」ことを考慮に入れています。
ドキュメントを読むのはめちゃくちゃしんどい
とはいえ、ドキュメントを読むのはとても体力を使います。
私もエンジニア4年目に突入しましたが慣れることはありません。(多分一生慣れない)
そして読むのが辛いのは大体以下の時です。
ドキュメント以外に分からないことが多すぎる
とあるライブラリだけが分からないのではなく、3つ4つ分からない概念がある。
よって、「何が分からないか分からない」状態に陥ります。
圧倒的な知識量によって情報オーバーロードになる時はマインドマップなどで整理することをお勧めします。「どこまで理解できて、どこから分からなくなっているのか」を分析するためです。
ドキュメントを読むための準備ができていない
準備と言うのは 「そのドキュメントがなんのために存在しているのか」を理解している状態 です。
ライブラリがあるのも過去に何かしら解決したい問題・ニーズがあったはずです。
こういった背景知識を簡単にでも頭に入れた状態で、公式ドキュメントを読んだり、手を動かした方がその技術の設計思想を理解しやすいはずです。
思想が理解できると「こんなメソッドが用意されてそう」「こんな感じで書けないかな?」と結構あたりが効くようになります(私の体感ですが)
公式ドキュメントを読むための土台を作るために、日本語の記事を読んだり・AIに質問することは大賛成です。ただ、「日本語記事だけ、AIに聞いただけ」はあまり賛成できません。必ず後で公式ドキュメントで裏をとることを推奨します。
公式ドキュメントを読む文化がない
悲しくもチーム・先輩が公式ドキュメントを読まないなら、若手にもその習慣は身に付くことはないです。チームを巻き込んで公式ドキュメントを読むなど、文化を育む努力も必要です。
チームに無能がいなくなる『メンバー全員で公式ドキュメントを読みあわせる』に感銘をうけた話。
という記事を読んでとても共感できました。
そういえば自分も公式ドキュメントの読み方を教わったことはないです。
「頑張って慣れるもの」と思い込んでいました。
こうした情報収集に関するメタ的な技術も教わる機会があってもいいかもと思いました。
「全員がドキュメントを読める訳ではない」というスタンスになると、コミュニケーションの方法が変わってくると思います。
ただ、「若手のみで読書会をする」ことに関して自分はあまり賛成しません。
慣れている人がドキュメントの勘所をピンポイントで教える方が圧倒的に効率的です。
何度もドキュメントを読む
公式ドキュメントを一発で理解するのは無理ゲーだと思っています。
(多分初回で読んでも5%も理解できていない気がする)
なので
- 実際に使うときに読む
- 空き時間で理解を深めるために読む
- 日を改めて読む
など、焦らず理解を深める機会を増やすことが必要です。
世界一流エンジニアの思考法 という本でも
「理解することに時間をかける」への言及があります。
「早く結果を出したい」「早くPRを出したい」と目先の成果ばかり求めて、
技術への理解を中途半端なまま放置してしまうことはありませんか?
(自分はその節がありました)
そういったスタンスが、成果物の質を下げる根本原因の一つのような気がしています。
理解に時間をかけることは情けなくないです。
むしろ偉いことだと思います。
学習初期こそ時間をかけて堅実に分からないことを一つずつ解消していきましょう。
※ 紹介した本の著者のnoteも勉強になるので、参考まで
プログラミングというより物事が出来るようになる思考
補足
弊社では「プログラミング未経験歓迎」のスタンスをとっており、その立場での考えです。
「経験をある程度積んだ社員が大半を占める」という状況では変わってくる話かもしれません。
まとめ
先輩
「ドキュメント読んだらわかる」発言には慎重になった方が良い
後輩
新人の頃に公式ドキュメントが分からないのは当然だから落ち込むことはない
公式ドキュメントは
- 信頼性がある
- 公式の書き方が載っている
- 網羅的な情報が載っている
から読むことに慣れる・理解できるように努力することは必要
一発で理解するのは無理ゲーなので、5%の理解を積み上げる
参考
チームに無能がいなくなる『メンバー全員で公式ドキュメントを読みあわせる』に感銘をうけた話。
プログラミングというより物事が出来るようになる思考
Comments
Excel VBAで仕事をしているのですが、有識者曰く、公式ドキュメントに嘘が書いてあることがあるのだそうです。さすがにその事実を知ったときは、膝から崩れ落ちて、頭を抱えました。。公式ドキュメントとは一体。。
あとそれに関連したことだと、MS社のドキュメントは機械翻訳で「何を言ってるんだね君は」状態なことが多いので、MS社に限らず、ドキュメントを読む際は翻訳を挟まず、原文を読むことをお勧めします。
むしろ「慈悲深い」方だと思えます.
少なくとも 何を読めばいいのか を指定してくれているので.
この場合,言った側は そのドキュメント を読めば大丈夫(なハズだ)だということを知っていて言ってるわけだし,
読んでみてわからない場合には「ここの話がちょっとわからないんですが…」って質問しても良さそう.
「ドキュメント読めよ」
だけに留まっている場合,無慈悲感が出てくると思います.
個人的な印象ですが、公式ドキュメントを読む難しさというのは、その充実さ故に目的の情報を探しにくい点にあると思っています。なので手っ取り早く結論だけ探したい時は私も個人ブログなんかで済ませます。
逆に情報のありかさえ見つけてしまえば、その内容は信頼性、充実性、(ものによりますが)見やすさ、全てにおいて多くの個人ブログよりも優れていると思います。
なので私としては公式のURLを探して渡してくれるのはむしろめちゃくちゃありがたいです。人によって考え方は様々ですが、そういう人もいます。
こんにちは。
公式ドキュメントを読む力を意識して付けるべきだろうと思います(学生時代からも)。先輩の指摘も、その意図であり、その力を持たないと評価されない(=お荷物?)と思ってのことかと思います。例えば英語 Wikipedia を楽に読みこなせるぐらいの力をつければ究極かもしれません。
なお、「岩波数学公式」の誤りを一年に一つ以上見つけられない学生は勉強不足だと、私の学生時代に言われました。
公式ドキュメントがない, 足りていない, 更新されていない, 間違っている, などよくあると思います. ここを読めば答えが分かるなんてすごくやさしいと思います. 最初から無理とわかっていることを指示しているようには見えないです.
ドキュメントを探索して自分で答えを見つけられるように, 早くなってほしいのではないでしょうか?
一口に公式ドキュメントを読めと言われても大抵巨大なので、あたりをつけられない状態でそれは言われたくないですね……
公式ドキュメントを参照させるなら「ドキュメントのどのページのどこ」まで指定してくれたほうが嬉しいですし、そのほうがお互いにかかる時間も減りそうです。
先輩へ「具体的に何ページの何行目」を示すよう求めることは非現実的だと思います(そこまで記憶しているわけでなく、調べさせることになるので)。
(なお旧日本軍の陸軍大学校の入学試験の口頭試問で、「陸軍教典の何ページの何行目の内容を回答せよ」と求めたそうです)
私もかつて、先輩として同様の回答したことあるかも、と思い、思い当たることをいくつか。
(1)後輩の知識・経験を把握してない時
わざとです。実力を試すためで、まずは出だしとしてドキュメント見てみて、と。英語力含め。
まずはドキュメントのありかを示して、それで解決すれば、OK。それだけで分からないようなら、個別対応したり、仕様・設計に関わる事柄なら、先輩が巻き取ってくれるはず。
→だから、後輩もドキュメント見ただけではどう分からないかを、忙しい先輩に簡潔に伝えないといけない。
(2)後輩の知識・経験を把握済みの時
信頼されている証拠です。周りからは先輩・後輩の関係かもしれませんが、その先輩にとっては、ほぼ同じ開発現場の同僚として見ているのでしょう。どうしようもない後輩なら手取り足取り、となるかもですが、今のお前ならこれだけで大丈夫だろ、と。そこはやはり、期待に応えないと。
(3)忙しい時
暫定的な対応です。一段落したら、後から「さっきの、分かった?」と、確認の一声掛けます。
(4)先輩も独自に調査中
後輩がドキュメントを見ている間に、先輩もお調べ中です。過去に似たようなことがあって、参考になるコードを探してたり、該当のサイト、社内のマニュアル等を検索中です。少し待ってると、五月雨に情報来るかも。
普段から、次はどの資格取得を目指しています、とか現状を伝えておくと、いいかもです。上の管理職からの後輩情報って、あまりにもざっくり感ありすぎて、もわもわっとし過ぎていますので。意外と、後輩の個人情報、現場に伝わってなかったりします。
これはテクノロジーというよりインタラクションの問題にも見えます。
日本のヒエラルキー構造の企業体では立場的に「投げる」という形をとりがちなのですが、
これを客観的に自制できるか、その一点だと思います。
「公式ドキュメントはここ(https://~~)ですが、ちょっと読みづらいのでこちらのページを先に読むと導入としてわかりやすいと思います。(https://~~)」
「ポイントとしては真ん中あたりの〇〇と△△かとおもいます」
「なにかありましたらお気軽に聞いてください」
って書くのは数分もかかりませんよね。
が、年齢なり役職の差があると「これやで(ポイ)」をしがちです。
「こっちのほうが年上だから数分の説明をオミットしていい」「役職が上だから数分たりとも自分がサービスする必要はない」という考えをどう自制できるか。
つまり相手を一人のビジネスパートナーとしてみるか、部下や上司としてみる(=江戸時代の丁稚奉公思想を令和の時代になぞる)か。
その人の好みしだいと思います。江戸時代が好きなら良いのでは。
欧米の職場ならば(?)、ある人が公式ドキュメントに沿わない内容の資料を作るもしくは発言等した際、周りの全員は無言でそれを認識し、マネージャはすぐにその人へ、職場が求める能力の不足とだけ告げ、来週から職場に来ないように命じると思います(今週採用された人でも翌週免職される)。これにより職場全員が常にエキスパートのみという状態が維持されます。なお日本以外では、職場で公式ドキュメント読んで下さいなどのアドバイスをしたり、能力を向上させようと教えたりすること自体が無いだろうと思います。
Let's comment your feelings that are more than good