ビジュアルコラボレーションSaaS『Strap』エンジニアリングマネージャーの西山です。

Strapのコンセプトとして、チームが「同じモノを見る」ことでチームとして共通認識を持つことが良いコラボレーションのために必要不可欠であると考えています。 Strapチーム自身も「同じモノを見る」ことで共通認識を揃えることをとても重視しているのですが、普段の活動の中で「具体例を挙げる」ことをチームが自然に行っていることに気がつきました。基本的なことでありながら忘れられがちな大事なこと。コラボレーションの中で「具体例を挙げる」ことの価値について、いろいろな場面を「例示」しながら書いてみます。

アウトラインは以下のような感じです。

具体例を挙げることで理解を深める
具体例を挙げることで誤りを検出する
「例示は理解の試金石」
ユースケースも具体例: 仮説を立てたらユースケースも考えよう

具体例を挙げることで理解を深める

説明しにくい話をするときは小さな例を挙げることから始めてみましょう。

例1: コーディング規約

エンジニアだとコーディング規約などガイドラインを用意して、それに対する具体例を付けていくことは多いかと思います。Strapチームでもこんな形で例を付けています。命名規則をGoodだけでなくBadの例も付けて、絵文字で表しているのが直感的に分かりやすいですね。

規約だけで伝えるのではなく、具体例が規約の意味を補強しているのが分かるでしょうか。

f:id:nsyee:20211224174534p:plain — コーディング規約の例

例2: Commit & Pull Requestガイドライン

もう少し大きな例で、GitのCommit & Pull Requestのガイドラインを挙げます。Strapチームではレビューの効率化のためにけっこう細かくルールを決めていて、それが明示的で分かりやすくもありつつ、テキストをちゃんと読まないとパッと理解できなくもあります。

f:id:nsyee:20211224174638p:plain — Commitガイドラインの例

それが以下のようにCommitの具体例があるだけで、テキスト自体が視覚情報として入ってきてスルッと認識することができます。ここでも、規約が具体例を規定するだけでなく、具体例からも規約の意味を補強しているような双方向の関係性を見ることができるでしょう。

f:id:nsyee:20211225122915p:plain — Commitの例

例3: Storybookやテストケースのシナリオ

プログラミングの例でいうと、Storybookやテストコードでコンポーネントや関数に対するテストケースやシナリオを洗い出す行為も「具体例」の例示です。

コンポーネントや関数を作成する人は、それらの具体的な使われ方を仕様から想定し、網羅的にパターンを列挙する
コンポーネントや関数を利用する人は、網羅された使い方のパターンを見て、それらの仕様を理解する

コンポーネントや関数の作成とstoriesやテストコードの作成は、お互いの結果をフィードバックし合いながら双方向に行われる。コードを書いている人は日々実践していることなので理解しやすいと思います。ここで重要なことは、コンポーネントや関数の作成者と利用者の間で具体例を通してコミュニケーションが行われているということです。具体例であるテストケースやシナリオを書く時は自分の仕様への理解を深めるとともに、レビュアーやチームメンバーが見て理解しやすい形で作成することが求められます。

f:id:nsyee:20211224174816p:plain — Storybookでコンポーネントの使い方を示す例

例4: UIの状態遷移の設計

Strapチームの特徴として、ビジュアルコラボレーションのツールであるStrapを自分たち自身で使い、設計ドキュメントのほとんどをビジュアルベースで作成していることが挙げられます。付箋エレメントの設計を例に紹介します。

UIの操作仕様やインタラクションの仕様の設計は、掛け算で組み合わせ爆発の起こる本質的に難しい作業となりますが、2次元の平面上に視覚的に配置することで理解を助けます。

UI設計に関しても、「UIコンポーネントと仕様」と具体例としての「利用パターンと状態パターン」は双方向に規定し合います。仕様からパターンが生まれ、パターン（具体例）の集まりが仕様を規定する関係性です。

付箋をめくるインタラクションのイメージを伝える参考画像も仕様の側に付記しているのも特徴的です。初期のデザインフェーズでよく用いられるムードボードがまさに具体例を目的とするものですが、言語化しにくい定性的な概念や価値判断の基準も、ビジュアル表現のOK/NGを具体例として挙げていくことで概念の輪郭が豊かに浮かび上がるように現れて伝えることができるでしょう。

f:id:nsyee:20211225113045p:plain — UIの状態遷移の設計の例

仕様と具体例の関係

f:id:nsyee:20211225141655p:plain

ここまで話してきたことをまとめます。

規約・仕様は、取りうる具体例の範囲を規定する
具体例が集まることで、規約・仕様の意味を肉付けし補強する
- 「言葉の意味とはその使用(use)である（意味の使用説）」
規約・仕様と具体例は双方向に作用し、互いに包み、包まれ合う関係をつくる

具体例を挙げることで誤りを検出する

具体例を挙げることの実用的な効能として、具体例から対象の誤りや矛盾に気づくことができる点があります。先に挙げた「例2: Commit & Pull Requestガイドライン」や「例3: Storybookやテストケースのシナリオ」で規約や仕様の具体例を挙げていく作業の中で、実際には互いに往復しながら完成度や解像度を高めていく作業となっていたと思います。「仕様 → 具体例」や「具体例 → 仕様」など一方向の作業でなく、「仕様 ↔ 具体例」のように往復する作業。具体例を考えることで仕様の不備や改善点に気が付き、仕様をアップデートすることで改めて具体例の適用例も解像度を高めていく。仕様などの抽象度の高い概念に具体例を与えていくことは、ある種の概念に対するテスト、デバッグとみなすことができるでしょう(「例示とはテストである」)。

Strapの開発にはまだ利用していないので余談となりますが、形式的に仕様記述したモデルに対して網羅的に性質検証するモデル検査器というツールがあります。ツールに指示して具体例を自動生成してもらうイメージですね。モデル検査器を用いることで仕様に対してプロトタイピングを行うようにトライ&エラーを高速に繰り返して品質を高めていくことができます。

モデル検査の分野の重要な仮説で「小スコープ仮説（モデルの不具合のほとんどは小さい範囲の探索で示すことができる）」というものがあり、具体例を挙げていくことの価値を示唆するものであると感じています。

代表的なモデル検査器の一つであるAlloy Analyzerを用いたモデリングについて過去のAdvent Calendarで書いているので、興味がある方はぜひ参照してみてください。

qiita.com

「例示は理解の試金石」

記事のタイトルですでに出落ち感ありますが、「具体例を挙げる」ことの価値について考えていたところでふと頭の中に降りてきたのが«例示は理解の試金石»です。小説『数学ガール』シリーズの中でたびたび登場する有名なスローガンです。

数学のように抽象的な概念に対して立ち向かう際に、具体と抽象の間を往復することで対象の理解を深めていく実践法であり行動指針です。

数学ガールの秘密ノート／数列の広場 2.3 数式を読む

«例示は理解の試金石»　―――
これは、僕たちが大事にしているスローガンだ。
本当に理解したかどうかを試すには、例を作ればいい。

・適切な例を作ることができるなら、自分は理解している。
・適切な例を作ることができないなら、自分は理解していない。

とてもシンプルな判断方法だ。

プロダクト開発という抽象度の高い課題解決を行う中で、具体的な使われ方のコンテキストを考えるユースケースもまさに例示=具体例じゃないか、という仮説の元にそのまま当てはめて僕らのスローガンを作ってみましょう。

«ユースケースはプロダクト理解の試金石»

プロダクトや機能に対するユースケースを挙げることができるなら、自分はそのプロダクト/機能の価値を理解している
プロダクトや機能に対するユースケースを挙げることができないなら、自分はそのプロダクト/機能の価値を理解していない

また、例示=ユースケースをコミュニケーションの道具として受け手の理解（= チームやステークホルダー）の確認にも適用できるでしょう。

提示されているユースケースに納得・共感できるなら、自分はそのプロダクト/機能の価値を理解している
提示されているユースケースに納得・共感できないなら、自分はそのプロダクト/機能の価値を理解していない

バッチリはまる感じがしませんか？妥当と思える実際的なユースケースを考えることが、自身やチームのプロダクト理解を試す試金石であると利用してみる価値はありそうです。

ユースケースも具体例: 仮説をつくったらユースケースも考えよう

Strapチームでは「この機能のユースケースは何か？」とエンジニア、デザイナー、プロダクトマネージャーなどロールを問わず常にWhyを問いかけていて、それが自然に行えていることがこのチームの力の源泉だと思っています。

開発現場あるあるとしては、ユースケースがしっかり議論されないまま機能実装されてしまうことは起きえます。

例えば、ゼロイチ開発のように解決すべき課題も解決法もまだはっきり見えていない仮説検証フェーズではいきなりHow/機能ベースの議論をしてしまいがちです。「僕の考えた最強の〇〇」みたいな（それ自体は悪いことではないです）。

別の場面では、プロダクト開発が軌道に乗り、問題領域への理解も深まり、ユーザーからのフィードバックも多く集まるようになったフェーズでも、すでに知っていることとしていろいろショートカットして機能ベースの議論をしてしまうことがあるでしょう。

その結果、誰がどんなときに使うの？ほんとにそれいるの？という点が不明なまま、細かい機能や重量級の機能がそのまま提供されてしまうなんてことに繋がります。チームやステークホルダーにプロダクトのアイデアの価値を伝えるために、そして自分自身がアイデアの価値の解像度をより高めるために、以下の観点を意識しながら想定するユーザーのユースケースを挙げてみましょう。

ユーザーに提供すべき価値は何か？
ユーザーのどんな課題を解決するのか？もたらされるアウトカムは何か？
ユーザーの行動(業務など)の中で実際にどのような場面で使われるか？

Strapでの事例として、プロジェクト立ち上げ時のまだ価値判断の拠り所が何もない時期に作成した、価値マップと呼ぶドキュメントがあります。Strapの提供価値を大分類5項目、小分類16項目に言語化して体系化し、それぞれの価値に紐づくユースケースをすべて洗い出し、ビジュアル化しました。価値やユースケースを実現する機能を開発タスクに落とし込み、優先度を付けてそれをロードマップに落とし込んでいく。ゴールとなるプロダクトの価値、ユースケース、機能、ロードマップがひと繋がりとなる価値マップは、不確実性の高いゼロイチフェーズでチームの羅針盤として機能しました。現在は具体的な課題解決フェーズに入っているため直接参照する機会は減りましたが、それでも新たな価値提案をする際は立ち返り参照する基準線となっています。

f:id:nsyee:20211225165517j:plain — プロダクトの価値基準を体系化した価値マップ

f:id:nsyee:20211225113116p:plain — それぞれの価値に紐づくユースケースを網羅

まとめ

チームと「同じモノを見る」ために、アイデアをよく表す具体例を挙げてみましょう。同様に、プロダクトに対する素晴らしいアイデアを思いついたら、まず具定例=ユースケースを挙げてみることを心掛けてみましょう。その際には、より具体的イメージを伝えやすいビジュアルコラボレーションツールを使って描いてみることがオススメです。

そこで挙げた具体例/ユースケースから自己フィードバック、あるいはチームからのフィードバックを得て、プロダクトや機能に対する自分自身の理解も一歩深めることができるはずです。