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

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

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

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

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

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

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

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

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

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

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

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

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

ドキュメントの例① 成果物（＝ドキュメント）の紹介

ドキュメントの例② 成果物（＝ドキュメント）の紹介

ドキュメントの例③ 成果物（＝ドキュメント）の紹介

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

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

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

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

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

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

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

teppeita

More Decks by teppeita

Other Decks in Programming

Featured

Transcript