公式ドキュメントとの正しい付き合い方+α

九州学生エンジニア交流会LT

Transcript

1. 公式ドキュメントとの 付き合い方+α 安達さくら/九州学生エンジニア交流会2023 - LT #KSEC_2023
2. 自 己 紹 介 安達さくら/saku X: @SakuOnTheWeb 佐賀大学理工学部情報ネットワーク| B4 | SCLA University of Technology Sydney, Information Technology majorで１年間留学し てました 🇦🇺 Cybozu株式会社 | 24卒Frontend engineer | 内定者アルバイト 　 - kintoneのフロントエンドリアーキテクチャPJに携わって ます 普段はWebフロントエンドの世界に生息しています 🌟 フロントエンド周りの話をするの好きです
3. 公式ドキュメントとの 付き合い方+α HOW DO YOU UTILIZE OFFICIAL DOCUMENTATION? 内 容 ※JS寄りの文脈になることをご了承くださいorz
4. 新しい技術を使う時 quiitaやzennの記事 が少なかったら諦めて いませんか？
5. デバッグの時 外部記事がなかったら 思考停止していませんか？
6. そんな時こそ 公式と 仲良く正しく向き合いな おしてみませんか？ 🫶🏻
7. そ ん な こ と 言 わ れ て も 、 公 式 っ て 誰 . . . ？ 俗にいう「公式ドキュメント」 OSSのGithubリポジトリ(Cloud系を除く) OSSコントリビュータの人(開発者の人)が出してる技術記事とか 個人的定義：“信憑性の高い”リソース
8. 俗にいう「公式ドキュメント」 step by stepのGetting Started的なもの プレイグラウンド｜｜APIの具体的な使用例｜｜Syntax etc... OSSのGithubリポジトリ コードベースレベルの仕様、PR、Issue、Changelog/ リリー スノート etc... 変化の激しいフロントエンドではwatchしておくことも大事だったりする 👀 OSSコントリビュータの人が出してる技術記事 信憑性高めの「私だったらこう使うね」 技術に対するその人なりの見解・裏事情 得 ら れ る も の
9. わかるけど... 読むのつらいよおおお 🤢
10. そ の 前 に . . . 個 人 的 に 「 公 式 」 に 飛 び 付 か な く て も い い と 思 っ て る ケ ー ス 複数の技術を統合する解決策を探しているとき エラーが何を指すのかそもそもわからないとき 嫌いなタイプの公式ドキュメントのとき
11. そ の 前 に . . . 個 人 的 に 「 公 式 」 に 飛 び 付 か な く て も い い と 思 っ て る ケ ー ス 1️⃣ 複数の技術を統合する解決策を探しているとき 新しいものを生み出したい時にアイデア・技術的な解決策を 得たい時は外部リソースを参考にした方が早いケースが多い
12. そ の 前 に . . . 個 人 的 に 「 公 式 」 に 飛 び 付 か な く て も い い と 思 っ て る ケ ー ス 2️⃣ エラーが何を指すのかもわからないとき ドキュメントにエラーをいちいち詰めてる余地はない stackover flowやOSSのissueを見にいく
13. そ の 前 に . . . 個 人 的 に 「 公 式 」 に 飛 び 付 か な く て も い い と 思 っ て る ケ ー ス 3️⃣ 嫌いなタイプの公式ドキュメントのとき 個人的に好きなドキュメント以外の時（ 👇好きなタイプ） 明確で短め コードブロックが各所に埋め込まれている example多め 願くばプレイグラウンド付き (tsのexampleがない)、なんかサイトの動作が悪い etc... 好きなタイプ　e.g.; zustand、mdn etc...
14. 公 式 に 苦 手 意 識 を も っ ち ゃ う 原 因 どこ読んでいいかわからん 何がどこに書いてあるかわからん それっぽいところ見てみたところで長い 長いのを頑張って読んでも明確な答えが見つけられない 見つけられても解決できない 😭 出てくる基礎的な単語がそもそもわからんくて離脱 MDN読んでる時にObjectってなんやねん、methodって なんやねんとなる 英語アレルギーあり・またはお使いの翻訳機にアレルギーあり
15. 公 式 に 苦 手 意 識 を も っ ち ゃ う 原 因 - 個 人 で な ん と か し て も ら う も の ( I M H O ) どこ読んでいいかわからん 何がどこに書いてあるかわからん それっぽいところ見てみたところで長い 長いのを頑張って読んでも明確な答えが見つけられない 見つけられても解決できない 出てくる基礎的な単語がそもそもわからんくて離脱 英語アレルギーあり・またはお使いの翻訳機にアレルギーあり →ドキュメント読むための勉強の一部だと思って調べる！ →with翻訳機で英語読めるくらいには！かかりつけ医にご相談を
16. 公 式 に 苦 手 意 識 を も っ ち ゃ う 原 因 - 解 決 策 何がどこに書いてあるかわからん →ドキュメントの構造を掴む→(自分側)解決したい対象を明確に する→ドキュメントに戻る
17. 公 式 に 苦 手 意 識 を も っ ち ゃ う 原 因 - 解 決 策 それっぽいところ見てみたところで長い →上から下に読むスキミングしながら読む、関係なさそうなとこ ろは一旦バッサリ「読まない」
18. 公 式 に 苦 手 意 識 を も っ ち ゃ う 原 因 - 解 決 策 頑張って読んでも明確な答えが見つけられない １：推測しながら読む「この人はつまり何を伝えたいんだろ う〜？」（理想は読み終わった後に一文要約できる） ２：例になりそうな箇所を見つける→具体的な実装をコードベー スを確認して得る -「例になりそうな箇所」：公式の「例」・codepenなど・Github で参考になりそうなリポジトリを検索
19. 公 式 に 苦 手 意 識 を も っ ち ゃ う 原 因 - 解 決 策 見つけられても解決できない（一旦完全に理解したけど、なん か上手くいかん） - 公式が提示する条件と、自分が用意している条件の差異を列挙 - Getting started・他のリポジトリがどういった環境で動作している のか調査する - 内部構造を見にいく - それに関するIssueを見る - 解決策が取り入れられるものであれば適用 - なければIssueとして報告
20. 今 日 伝 え た か っ た こ と 🌟 読み方がわかれば公式は 格段に読みやすくなる！！ 公式と正しく向き合って、快適なプログラミング・デバッグライフを 🏗️❤️