Slide 1

Slide 1 text

GraphQLの社内ドキュメント を作った話 2023-07-06 tsukiji.graphql 株式会社マイベスト 竹尾 哲平(@_teppeita)

Slide 2

Slide 2 text

● 竹尾 哲平 ● @_teppeita ● フロントエンドエンジニア ● 株式会社マイベスト ● 人の選択をサポートするサービス ● 商品を自社で検証してランク付け 自己・自社紹介 ドキュメント作成の背景

Slide 3

Slide 3 text

今日伝えたいこと GraphQLは 社内向けのドキュメントを整えると 運用コストが減るので オススメ

Slide 4

Slide 4 text

今日話すこと ▶ 作成の背景と解決したかった課題 ▶ ドキュメント作成の進め方 ▶ 成果物(=ドキュメント)の紹介 ▶ 結果どうなったか

Slide 5

Slide 5 text

GraphQLは2019年に導入 バックエンドはRailsなので、graphql-rubyを使用 クライアントはApolloClientを使用 ここ1年で、 フロントエンドの構成を、Rails/一部Reactから、ほぼ全画面をNext.jsに置き換え それに併せて、GraphQLのAPIも全面的に実装 GraphQLの使用場面が急増した結果、いくつかの課題が顕在化した マイベストとGraphQL 作成の背景と解決したかった課題

Slide 6

Slide 6 text

● 入社後に初めてGraphQLを触る人が多い ● 概念的な説明から具体的な実装方針まで理解が必要 ● 毎回誰かが時間をかけて説明しなければならない 課題①:オンボーディング 作成の背景と解決したかった課題

Slide 7

Slide 7 text

● 設計・実装方針を共有しきれていなかった ● コードレビューで都度コメントして共有する必要があり負荷が高 かった ● ルールを決められていない箇所で、統一感の無いコードがどんどん 増えていった 課題②:設計方針の共有 作成の背景と解決したかった課題

Slide 8

Slide 8 text

→結果 「大まかな方針は分かったけど、具体的な実装はどうすれば良い?」 「今回読んだ人と読んでない人の格差が出るのでは?」 まずトライしたこと 作成の背景と解決したかった課題

Slide 9

Slide 9 text

課題を解決するには、 社内向けのドキュメントが必要 だと判断

Slide 10

Slide 10 text

今日話すこと ▶ 作成の背景と解決したかった課題 ▶ ドキュメント作成の進め方 ▶ 成果物(=ドキュメント)の紹介 ▶ 結果どうなったか

Slide 11

Slide 11 text

枠組みを整理 ドキュメント作成の進め方 ページ構成 フォーマット トピック

Slide 12

Slide 12 text

「手が空いた時に書く」だとなかなか進まないので、 毎週1時間MTGをセットして、その中で作業を進めることに。 議論しながらルールを整理する会を実施(勉強会も兼ねて) ドキュメント整理会を実施 ドキュメント作成の進め方

Slide 13

Slide 13 text

今日話すこと ▶ 作成の背景と解決したかった課題 ▶ ドキュメント作成の進め方 ▶ 成果物(=ドキュメント)の紹介 ▶ 結果どうなったか

Slide 14

Slide 14 text

- 全体像 - GraphQLについて学ぶ - マイベストでの使われ方のポイント - 設計思想 - バックエンド - キャッシュ - ページネーション - N+1 - フロントエンド - ファイルの命名と配置 - 型の自動生成 - Fragment Colocation ページ構成(一部抜粋) 成果物(=ドキュメント)の紹介

Slide 15

Slide 15 text

ドキュメントの例① 成果物(=ドキュメント)の紹介

Slide 16

Slide 16 text

ドキュメントの例② 成果物(=ドキュメント)の紹介

Slide 17

Slide 17 text

ドキュメントの例③ 成果物(=ドキュメント)の紹介

Slide 18

Slide 18 text

今日話すこと ▶ 作成の背景と解決したかった課題 ▶ ドキュメント作成の進め方 ▶ 成果物(=ドキュメント)の紹介 ▶ 結果どうなったか

Slide 19

Slide 19 text

オンボーディングでの 個別フォローが 最小限で済むように😃

Slide 20

Slide 20 text

コードレビューも 方針が明文化されているので 負荷が激減😁

Slide 21

Slide 21 text

設計で悩んだら 「整理してドキュメントに書きましょう」 という流れができた🤩

Slide 22

Slide 22 text

結論 社内ドキュメントを整理したら GraphQLの運用がスムーズになった

Slide 23

Slide 23 text

これからも GraphQLと仲良く🤝 ご清聴ありがとうございました