こんにちは。株式会社 Sun Asterisk (Sun* Inc.)でフロントエンドエンジニアをやっている松本(queq1890)です。普段は React.js / TypeScript を使ってフロントエンドアプリケーションの開発を行いながら、フロントエンドエンジニアの採用をお手伝いしたりしています。2019 年に入社してから、弊社のベトナム・ハノイ拠点で働いていましたが、2021 年に帰国し、現在はリモート中心のスタイルで勤務しています。以前、社内でインタビューしていただいた際の記事があるので、筆者については是非そちらをご覧ください。
本記事では、弊社のベトナム拠点のメンバーと行っている、社内向けフロントエンドアプリケーションの実装ガイドラインを作成する取り組みについて紹介します。
ガイドラインを作ることになった背景
弊社はスタートアップからエンタープライズの新規事業立ち上げ・DX 支援に至るまで、伴走するクライアント企業の規模・フェーズを問わず幅広く支援させていただいています。約 100 ~ 150 程のプロジェクトが常時立ち上がっており、ビジネス職・テック職・クリエイティブ職が協力して日々サービスの開発・改善を行っています。
これらのプロジェクトそれぞれが円滑に運営されるよう、プロジェクトを横断して支援する取り組みがいくつか行われています。支援の一環として、弊社のベトナム拠点では TSU(Technology Support Unit) という部署が今年の春新設され、ベトナム拠点のエンジニア主導で開発されているプロジェクトについて、プロジェクトの進行上生じた技術的な問題の解決を手伝ったり、技術選定・実装方針・アーキテクチャの壁打ちに乗ったり、といった活動を行っています。
TSU が支援の対象としている技術領域には当然 Web・フロントエンド領域も含まれています。TSU が活動を開始してしばらくすると、社内に複数存在しているフロントエンドプロジェクトの技術選定・実装方針・アーキテクチャが、各プロジェクトによってまばらであることが明らかになりました。プロジェクトによって、背景・コンテキストが異なるので、最終的な方針決定は現場のリードエンジニアに委ねつつも、しがらみなく技術選定が行える場合の理想の技術選定・実装方針・アーキテクチャを言語化しておくことで、社内で議論を行う際のベースラインを設けられるのではという話になり、フロントエンドアプリケーションの実装ガイドラインを作ることになりました。
私は、ベトナム拠点のメンバーだけではなく、日本で働いているメンバーの意見も取り込みたいといった理由で、プロジェクトを開始するタイミングで声を掛けていただき、チームに合流しました。
なぜ boilerplate / package ではないか
ガイドラインを作成する話が挙がった際に、ガイドライン以外の方法で理想の技術選定・実装方針・アーキテクチャを定義することも検討されました。具体的には、開発を bootstrap するための boilerplate を開発して配布する方法・再利用可能な実装を npm package 化して配布する方法等です。しかしながら、下記の理由からまずはガイドラインを用意し、その運用の結果を元に、実装を伴う施策を実施するかどうかを決めることにしました。
- パッケージ化した場合のメンテナンスコスト
- 実装が deprecated になった時に、配布するパッケージを利用している全てのプロジェクトで負債になる可能性がある
- 依存パッケージにセキュリティ上の問題が見つかり、配布するパッケージを修正したとして、配布パッケージを利用している全ての社内プロジェクトでアップデートが行われることを担保できるか?
- ただし、ガイドラインにも継続的なメンテナンスは必要
- プロジェクト側のエンジニア達に対して、本当に必要な実装を提供できるか分からない
ガイドラインの作成フロー
ガイドラインは下記のフローで作成しています。
前提
- ガイドラインの執筆に参加するメンバーにはそれぞれメインとなる担当プロジェクトがあり、ガイドラインの執筆はベストエフォートで行う
- ベトナム・日本といった拠点を問わず利用できるガイドラインにするため、英語で執筆する
- フロントエンドのガイドラインと銘打ってはいるが、本ガイドラインでは React.js + TypeScript を使ったスタック、特に Next.js を採用したスタックを中心に取り扱う
1.ガイドラインを配置するための GitHub リポジトリの作成
はじめに、執筆したドキュメントを格納するための GitHub リポジトリを会社の org 配下に作成しました。GitHub をドキュメント置き場として選んだ理由は、2 つあります。
-
- 執筆を行うエンジニアが慣れているツールである
-
- ガイドラインが社内向けに公開された後に、誰でも Issue / PR を open できるようにして、ガイドラインの修正を気軽に行えるようにしたい
2.スケルトンのドキュメントを作成
ガイドラインを 1 人で書き切るのは大変だと考えたため、ドキュメントに記載したいおおよその内容を予め決めておいて、チーム内のエンジニアで分担して執筆をする方針を取りました。
具体的には、ガイドラインで取り扱いたいトピックを決め、トピック毎に空のマークダウンファイルを作成した後、各マークダウンファイルで h2/h3 ぐらいまでドキュメントの構造を決め、その heading 内でカバーしたい内容について TODO コメントを記載しました。ここまでやったタイミングでチーム内のフロントエンドエンジニアにレビューを依頼し、内容に過不足がないか確認をしてもらいました。
マークダウンに TODO コメントを記載した diff のスクショ
2022 年 12 月現在では、下記のトピックをガイドライン上でカバーする予定です。記載するトピックは、bulletproof-react の docs を大いに参考にしています。
- Setting up Project
- Project Configuration
- Project Structure
- Data Fetching and Rendering Strategy
- State Management
- Styling
- Authentication
- Forms and Validations
- Typings
- Storybook
- Testing
- Deployment
- SEO
- BFF
- Common Anti Patterns
3.執筆
ここまでで大まかにドキュメントに記載したい内容は決まったため、誰がどのドキュメントを書くかを決め、分担して執筆を進めていきます。各担当者は、執筆が完了したタイミングで PR を開き、チームのメンバーにレビュー依頼をします。ドキュメントに記載する内容で検討が必要な場合は、PR 上で議論を行い、approve された PR は merge されガイドラインに取り込まれます。
バリデーションについて記載する doc の PR で、yup を記載するかどうか議論している様子
ガイドラインを構成するドキュメントの大半は、そのドキュメント内で取り扱うトピックについて、どのような実装のオプションがあるか・どのような場合にそのオプションの採用を検討するかを解説する形で執筆されています。
Testing について解説しているドキュメントの ToC
課題
現在も絶賛執筆中のガイドラインですが、課題も多くあります。
作成時点での課題
メンバーが執筆を行う時間の確保
このガイドラインの作成に関わっているメンバーは、ほぼベストエフォートで参加しています。メインで担当しているプロジェクトが忙しくなると、当然ドキュメントの執筆にあてられる時間はなくなります。一時期、全く PR が出ない期間もありました。
対策として、ドキュメントの執筆に関わるメンバーを増やし、現在はガイドライン作成完了の目処がつくところまで来ましたが、今後のガイドラインの運用・改善フェーズを今のベストエフォートのメンバーのみで実施できるかは分かりません。ガイドラインに関して自分が使える時間を増やすため、自分がメインで担当しているプロジェクトの稼働を調整することを検討しています。
執筆中もライブラリは更新され続ける
今回は予めドキュメントでカバーしたいトピックを決めてから分担して執筆を開始しましたが、ガイドライン中で取り扱いたいライブラリ群も、絶えず更新され続けます。執筆を開始してから一番大きかった更新は、Next.js 13の発表です。app ディレクトリの登場を受け、ディレクトリ構成について取り扱っているドキュメントは更新を余儀なくされています。
今後の課題
実プロジェクトへの導入
元々予定していた分のガイドラインの執筆が完了したら、今度はそのガイドラインを実際のプロジェクトで運用してみる必要があります。まずはガイドラインの執筆に関わったメンバーがリードを務めるプロジェクトで運用してみて、効果があるかどうかの検証・改善点の収集を行う予定です。
改善のルール整備
「メンテナンスコストが掛かるため、実装ではなくガイドラインを作ることにした」と、この記事の冒頭で触れましたが、実プロジェクトでの運用を受けてのフィードバック反映・ライブラリの更新への対応など、ガイドラインも継続的なメンテナンスが必要になります。これらの改善をどのように行っていくか、まだチーム内で議論できていないため、これらを決めて改善を回していく必要があります。
まとめ
この記事では、自分が作成に関わっているフロントエンドの実装ガイドラインについて、作ることになった背景・作成フロー・作成にあたっての課題を紹介させていただきました。はじめての試みで詰まるポイントも多いですが、チームで少しずつ改善しながらガイドラインの整備を進めていければと思います。また、作成されたガイドラインそのものの公開や、運用・改善フェーズに入ってから得られた知見についても、今後まとめてシェアできればと考えています。
Sun* Advent Calendar 2022、明日はデザイナーの鈴木さんから、「Sun*デザイナーチームが共通言語をつくったはなし」 というテーマの記事が公開される予定です。本記事で紹介させていただいた、フロントエンドのガイドライン作成とも通ずる部分があると思うので、是非併せてご覧ください。
Discussion