デザイナーとエンジニアの協働を促進させるために社内 wiki にドキュメントを作成しています

こんにちは、Gaji-Labo フロントエンドエンジニアの石垣です。

2023年9月8日にUIT Meetup vol.20『これがぼくらのスタンダード』というイベントに登壇させていただきました。

今回の記事ではその登壇内容の補足として、標準を定着させるために具体的にどのようなドキュメントを作成しているのかをご紹介します。

登壇の内容は以下のイベントまとめ記事に記載しておりますのでそちらもご覧ください。

https://gaji.jp/blog/2023/09/14/16942/

登壇内容の振り返り

LTでは、OpenAPI、Storybook、Figma など Web アプリケーション開発の上でデザイナーとエンジニアが協働しやすくなるワークフローを標準化し、それを定着させるためにワークフローを社内 wiki に策定しているという話をさせていただきました。

具体的には、 esa を社内 wiki として使用し、そこにデザイナーとエンジニアの協働のために必要なワークフローやドキュメントを策定しています。

デザイナーとエンジニアの協働のためのドキュメントの一例

その社内 wiki 項目の内容を、「デザイナー向けコンポーネントライブラリ概要」という項目を一例にご紹介します。

このドキュメントは、デザイナーがコンポーネントライブラリを使用する際に必要な情報をまとめたものです。Gaji-Labo では現在主に Storybook を使っているため、Storybook を題材にしています。

ここで重要な観点は「デザイナーとエンジニアが協働するために必要な情報をまとめる」ということです。Storybook の概要は公式ドキュメントを見れば載っているので詳しい説明は省略しています。

その代わりに、より具体的な案件作業にあたって、なぜコンポーネントライブラリを使うのか、コンポーネントライブラリを使っているとエンジニアとデザイナー双方にどのようなメリットをもたらすのかを詳しく記載しています。

例えば「コンポーネントのレビューが容易になる」「実装済みコンポーネントの一覧を確認できる」「コンポーネントが持つバリエーションを画面上で確認できる」のような、実感しやすいメリットを挙げ説明する形にしています。

ドキュメント策定の流れ

「デザイナー向けコンポーネントライブラリ概要」は、フロントエンドエンジニアである自分が土台を作り、社内デザインチームにレビューをしてもらいながら作成しました。

当然ながら、協働するドキュメントを作るときにエンジニアやデザイナーの視点のみで作成すると、協働する相手にとって必要な情報が抜け落ちてしまう可能性があります。

そのため、作成しながらコミュニケーションを取り、互いの領域について理解を深めながらドキュメントを作成することが重要です。

しかしドキュメントによっては、エンジニアかデザイナーのどちらかが理解していればいい情報もあり、関連する情報をすべて記載するとドキュメントが肥大化してしまい逆に使いづらくなってしまう可能性もあります。その場合は項目のスコープを設定し、エンジニアとデザイナー双方に必要な情報とそうでない情報を切り分けることも必要でした。

ドキュメントを作成しているなかでの学び

協働を促進させるドキュメントにはエンジニアとデザイナーの双方の視点が必要なため、作成しているなかで用語について認識が異なっていたりすることがありました。

例えば「コンポーネント」という語も、普段自分は無意識に React コンポーネントのことを指しているのですが、「コンポーネント」の語一つ取ってもさまざまな意味があることに気づきました。

先のLTで用語集を策定している話もしましたが、エンジニアとデザイナーの双方が同じ理解を持てるように用語一つ一つの認識を共有することが重要だと感じました。

おわりに

今回は「デザイナー向けコンポーネントライブラリ概要」という項目を一例にしましたが、それだけでなく命名規則などの様々な項目を作成しています。

今後も引き続き、エンジニアとデザイナーの協働を促進するために必要なワークフローやドキュメントを策定していきます。