システム開発の認識齟齬を防ぐために「共通用語集」を作ろう

4 min read読了の目安(約4000字

プロローグ

現代のシステム開発において、あるあるなのが「認識齟齬」

要件定義をいくらやろうとも、何度打ち合わせをしようとも、

  • 「何で仕様どおりにエンジニアは作らないんだ!」(POブチギレ)
  • 「こういうつもりで要求したわけじゃないんですが」(クライアント困惑)
  • 「要件の中で同じ意味の単語が違う表現で使われている、、、」(エンジニア実装ペンディング)
    というコミュニケーションミスは跡を絶ちません。

各工程でのインプット・アウトプット/各ステークホルダーを明確に定義しているようなウォータフォールな開発プロジェクトですら、上記のようなコミュニケーションミスが起きることをよく目にします。
いわんやアジャイル開発をや、です。

アジャイル開発におけるドキュメントの「価値」とのバランス

アジャイルソフトウェア開発宣言では、ドキュメントに関する「価値」を下記のように定義しています。

...
包括的なドキュメントよりも動くソフトウェアを、
...

価値とする。すなわち、左記のことがらに価値があることを
認めながらも、私たちは右記のことがらにより価値をおく。

(参考)https://agilemanifesto.org/iso/ja/manifesto.html

よってアジャイル開発では、ウォーターフォール開発のような「包括的な」ドキュメントが推奨されない中で、ステークホルダー間の認識のすり合わせができるものが必要になります。

このアジャイルソフトウェア開発宣言で謳われているのは、「動くソフトウェア」で認識のすり合わせをしていこう、ということになるのですが、「左記のことがらに価値があることを認めながらも」と記載されているように、必ずしもドキュメントを全く準備しなくていいということでもないと考えています。

アジャイル開発におけるでも使える「共通用語集」

包括的なドキュメントを作る時間はない、でもステークホルダー間の無駄な認識齟齬は防ぎたい、そんなニーズに適うドキュメントが表題にある「共通用語集」になります。

「共通用語集」とは

  • システム開発に関連する全てのステークホルダーがシステムにおいて関心の対象としている用語、およびその定義の一覧

になります。
※ドメイン駆動設計の「ドメインオブジェクト」と呼ばれるものが、この「共通用語」に該当するとも言えます。

アウトプットのイメージとしては、下記のようにエクセルやスプレッドシートを使って、用語と定義の組み合わせを表形式の一覧にしたものになります。

# 用語名 定義
1 管理者 特定のプロジェクトの遂行に責任を持つ人。管理者であると同時に、後述のプロジェクトのメンバーでもある
2 メンバー 特定のプロジェクトにアサインされた「管理者」以外の人
3 プロジェクト 企業のミッションに紐づく、特定の目的と3ヶ月以上の期間を持つ計画の一単位のこと。配下に責任者を最低一人含むメンバーとTODOが存在する
4 状況 プロジェクトの進捗の状況のこと。「実行前」「実行中」「中止」「完了」の4種類が存在する
5 TODO メンバーがプロジェクトの目的を達成するために、期限内に実施する仕事のこと

「共通用語集」を作ると何がいいか

「共通用語集」を作ると、システム開発における用語に関する認識のすり合わせを速いスピードでできます。
たかが「用語」されど「用語」。使用している単語がそれぞれ何を意味しているのか改めて明確にすることで、システムに関わるさまざまなステークホルダーがメリットを享受することができます。

  • For クライアント(ユーザー)
    • (toBサービスの場合)業務で使用している用語を改めて定義することで、クライアント自身も用語間の関連を明確に言語化することができる
    • (toCサービスの場合)サービス内で使用されている用語の意味が統一されているので、今までにない新しい概念であっても理解がしやすくなる
  • For PO(PM)
    • クライアントが使用している用語に関する認識齟齬を仕様を作成する前に防ぐことができる
    • (特に業務システムの場合、業界独特の用語に関して、開発側の理解が足りておらず、結果としてどんどん本来の要望からかけ離れた仕様ができてしまうケースがある)
  • For デザイナー
    • 画面に表示する用語の定義を自分でする必要がない
    • OOUIベースでの画面設計をする際、「概念モデル」で使用されている概念をベースに画面コンポーネントを設計できる
  • For エンジニア
    • 詳細設計をする際、ステークホルダーと認識のすりあった「概念モデル」をベースに設計ができるので、後戻りのリスクを押さえられる
    • 詳細設計したときに気づきがちな用語や表記のブレを、事前に解消することができる
  • For マーケティング/営業
    • サービスで使用されている新しい概念の定義が明確なので、マーケティングメッセージにブレが生じにくくなる

「共通用語集」の作り方

上記のメリットがある「共通用語集」についてですが、簡単に作成の仕方をまとめます。
「共通用語集」作成では、要求に出てくる「名詞」をどれだけ正確に抽出することができるか、が鍵になります。

1. 要求の一覧を作成する

例えばとあるプロジェクト管理ツールの要求が下記のようにあったとしましょう。

  • 管理者はプロジェクトを作成できる
  • 管理者はプロジェクトの状況を確認できる
  • 管理者はプロジェクト内のTODOを作成できる
  • 管理者はTODOにメンバーをアサインできる
  • メンバーはプロジェクト内のTODO

2. 要求から「用語」を抽出する

上記の要求から「用語」、名詞を抽出していきます。

  • 管理者
  • プロジェクト
  • 状況
  • TODO
  • メンバー

3. 用語を「アクター」と「対象」に分ける

抽出した用語を主語になりうる「アクター」と目的語なりうる「対象」に分けます。

  • アクター
    • 管理者
    • メンバー
  • 対象
    • プロジェクト
    • 状況
    • TODO

アクターは基本的にはシステムのユーザーになることが多いですが、他に「連携先のシステム」などがアクターになりえます。

4. 用語の定義をする

分類した用語に関して、それぞれ何を意味しているのか定義をしていきます。
用語の重要度に応じて、定義の粒度は変更してもいいですが、ここをサボってしまうと「同じ単語を使っていたが実は違う意味の認識だった」という冒頭の認識齟齬が生まれてしまうので、最低でも一行程度の定義文は記載するようにしましょう。

  • アクター
    • 管理者
      • 特定のプロジェクトの遂行に責任を持つ人。管理者であると同時に、後述のプロジェクトのメンバーでもある
    • メンバー
      • 特定のプロジェクトにアサインされた「管理者」以外の人
  • 対象
    • プロジェクト
      • 企業のミッションに紐づく、特定の目的と3ヶ月以上の期間を持つ計画の一単位のこと。配下に責任者を最低一人含むメンバーとTODOが存在する
    • 状況
      • プロジェクトの進捗の状況のこと。「実行前」「実行中」「中止」「完了」の4種類が存在する。
    • TODO
      • メンバーがプロジェクトの目的を達成するために、期限内に実施する仕事のこと

5. 用語の定義に関してステークホルダー間で認識のすり合わせを行う

先述した各ステークホルダー(ユーザー、PO、デザイナー、エンジニア、マーケティング/営業)に作成した用語集のレビューをしてもらいます。
もし作成した用語集とステークホルダーとの認識が大きい場合には、そのステークホルダーを交えて用語集を作り直すのも一つの手でしょう。開発メンバーがユーザーなど他のステークホルダーの人と直接コミュニケーションを取るいい機会にもなります。

「共通用語集」を作ったあとは

共通用語集を作ると先述の通り、各ステークホルダーの業務がこの「用語」をベースにして進むことになります。

  • For PO(PM)
    • 用語をベースにして仕様を策定することができる
  • For デザイナー
    • 用語をベースにしてOOUIを設計することができる
  • For エンジニア
    • 用語をベースにしてテーブル設計することができる
  • For マーケティング/営業
    • 用語をベースにしてユーザーへのメッセージ(営業資料や広告)などを作成することができる

また、プロジェクトが進むたびに、最初に定義した用語が実は違う意味だったことが判明することがあります。そのときには、最初の定義にこだわらずにすぐに新しい定義に修正して、再度その定義があっているかどうかステークホルダーに確認を取りましょう。
必ずしもプロジェクトの初期に全ての用語が洗い出せるとは限らないので、共通用語集もソースコードと同じく変更に対する柔軟性を持たせておきます。そうすることで、最初の共通用語集の作成に必要以上に時間を割くこともなくなります。

最後に

今回はドキュメントとして共通用語を作成するメリットとそのやり方について解説しました。
機会があれば、今後はこの共通用語を使ってOOUIやドメインモデルを設計する方法についても解説したいと思います。