技術とかの雑なToday I Learnedメモ

公式ドキュメントの読み方という記事

公式ドキュメントの読み方という記事を読んだ

リーディングリスト消化

公式ドキュメントの読み方

公式ドキュメントは、OSS においてはソースコードと双璧をなす最も信頼できる資料のひとつです。(引用)

これ、本当にそうだなと思うときはもちろん何度もあるんだけど、第三者の日本語記事が充実している場合はそうじゃない状態で解決してしまうこともあって、そうなるとそれで解決するならそっちのが楽だよね〜となるにはなる。

検索のうまさというか記事の読み方のうまさというか、「この記事は信頼できそう」みたいなのがなんとなくで分かってくるようになる、気がする。

まあそれでも公式ドキュメントを有効活用できるのが一番いいんですけどもね。

公式ドキュメントを見るほうがいい理由に

  • 信頼性
  • 百戦錬磨

とある。

信頼性はもちろんそうで、百戦錬磨のほうは最近 GitHub の Issue で解決したことがあるので本当にそうだなと思う(最近というか昨日)

自分が悩んでいることは大体他の誰かが既に悩んでいて Issue を上げていたりするので、そういう Issue を GitHub で見つけると解決にぐっと近づくと思う。

ただその Issue の探し方がエラーメッセージとかしかないので、英語力を鍛える必要がある……。

実装よりもドキュメントを読む、まあ分かるというかそっちのほうが明らかに近道。

たま〜にドキュメントに書いてないとこまで深堀りするときがある気もするけど、大体ドキュメントと Issue をちゃんと読むほうがいいかな〜という感覚はなんとなくある。

公式ドキュメントの読み方、結構 Getting Started を読み飛ばすときがあるんだけど、意外と「こういう場合はここを読んでね!」みたいなことが書いてあったりするんだよなあ。

でも大体は API Reference を探すことになる気もする。あんまり Example で助かったことはない気もする。

ドキュメントが古いというパターンにはあんまり当たったことはないとは思うけど、たま〜にそういう可能性があるのはなんとなくわかる気もする。あとドキュメントが指し示しているバージョンと自分の手元のライブラリのバージョンが違くて書いてあることが違う!となったこともあるので、バージョンの確認は大事だなと思う。

React のドキュメントには React + TypeScript の使い方の説明 がありますし、Jest のドキュメントには Jest + Webpack のセットアップガイド があります。(引用)

ここらへんのエコシステムが充実しているようなものになってくると、組み合わせて使うドキュメントも豊富になっていて本当にすごい。

元になった記事が出典にあった。

抹茶氏さんは Twitter を使っています 「新人プログラマをレビューで殺さない方法 - Qiita > 公式ドキュメントで殴る > 個人的に、一番辛いレビューがこれです。致命傷です。 これマジなのか…… https://t.co/0V0MkI6Jsk」 / Twitter

この記事ざっと読んだんだけど、タイトルの時点で新人の人にはかなり恐怖を抱かせるし、正直もうちょっと表現方法を考え直したほうがいいのではないのかなと思う。殺すみたいな言葉はプロセスとかだけに使ったほうがいいと思う派です。