GraphQLの社内ドキュメントを作った話

2023/07/06 tsukiji.graphqlで発表したLTのスライドです

Transcript

1. GraphQLの社内ドキュメント を作った話 2023-07-06 tsukiji.graphql 株式会社マイベスト 竹尾 哲平（@_teppeita）
2. • 竹尾 哲平 • @_teppeita • フロントエンドエンジニア • 株式会社マイベスト • 人の選択をサポートするサービス • 商品を自社で検証してランク付け 自己・自社紹介 ドキュメント作成の背景
3. 今日伝えたいこと GraphQLは 社内向けのドキュメントを整えると 運用コストが減るので オススメ
4. 今日話すこと ▶ 作成の背景と解決したかった課題 ▶ ドキュメント作成の進め方 ▶ 成果物（＝ドキュメント）の紹介 ▶ 結果どうなったか
5. GraphQLは2019年に導入 バックエンドはRailsなので、graphql-rubyを使用 クライアントはApolloClientを使用 ここ1年で、 フロントエンドの構成を、Rails/一部Reactから、ほぼ全画面をNext.jsに置き換え それに併せて、GraphQLのAPIも全面的に実装 GraphQLの使用場面が急増した結果、いくつかの課題が顕在化した マイベストとGraphQL 作成の背景と解決したかった課題
6. • 入社後に初めてGraphQLを触る人が多い • 概念的な説明から具体的な実装方針まで理解が必要 • 毎回誰かが時間をかけて説明しなければならない 課題①：オンボーディング 作成の背景と解決したかった課題
7. • 設計・実装方針を共有しきれていなかった • コードレビューで都度コメントして共有する必要があり負荷が高 かった • ルールを決められていない箇所で、統一感の無いコードがどんどん 増えていった 課題②：設計方針の共有 作成の背景と解決したかった課題
8. →結果 「大まかな方針は分かったけど、具体的な実装はどうすれば良い？」 「今回読んだ人と読んでない人の格差が出るのでは？」 まずトライしたこと 作成の背景と解決したかった課題
9. 課題を解決するには、 社内向けのドキュメントが必要 だと判断
10. 今日話すこと ▶ 作成の背景と解決したかった課題 ▶ ドキュメント作成の進め方 ▶ 成果物（＝ドキュメント）の紹介 ▶ 結果どうなったか
11. 枠組みを整理 ドキュメント作成の進め方 ページ構成 フォーマット トピック
12. 「手が空いた時に書く」だとなかなか進まないので、 毎週1時間MTGをセットして、その中で作業を進めることに。 議論しながらルールを整理する会を実施（勉強会も兼ねて） ドキュメント整理会を実施 ドキュメント作成の進め方
13. 今日話すこと ▶ 作成の背景と解決したかった課題 ▶ ドキュメント作成の進め方 ▶ 成果物（＝ドキュメント）の紹介 ▶ 結果どうなったか
14. - 全体像 - GraphQLについて学ぶ - マイベストでの使われ方のポイント - 設計思想 - バックエンド - キャッシュ - ページネーション - N+1 - フロントエンド - ファイルの命名と配置 - 型の自動生成 - Fragment Colocation ページ構成（一部抜粋） 成果物（＝ドキュメント）の紹介
15. ドキュメントの例① 成果物（＝ドキュメント）の紹介
16. ドキュメントの例② 成果物（＝ドキュメント）の紹介
17. ドキュメントの例③ 成果物（＝ドキュメント）の紹介
18. 今日話すこと ▶ 作成の背景と解決したかった課題 ▶ ドキュメント作成の進め方 ▶ 成果物（＝ドキュメント）の紹介 ▶ 結果どうなったか
19. オンボーディングでの 個別フォローが 最小限で済むように😃
20. コードレビューも 方針が明文化されているので 負荷が激減😁
21. 設計で悩んだら 「整理してドキュメントに書きましょう」 という流れができた🤩
22. 結論 社内ドキュメントを整理したら GraphQLの運用がスムーズになった
23. これからも GraphQLと仲良く🤝 ご清聴ありがとうございました