👏

draw.ioで実装の仕様書を書いて渡す

2022/01/18に公開約1,900字

draw.ioってめちゃくちゃ便利ですよね。最近は何をするにしてもdraw.ioを使用している気がします。例えばこんなときに私はdraw.ioを書いてます。

  • メンバーにシステム感のつながりを教えるとき
  • terraformなどで構築したAWSのドキュメント
  • オフショア開発でベトナムで開発しているヒトに仕様や実装の方針を伝えるとき
  • chatベースでは伝わりにくい時に図を書いて渡す

今回は、オフショア開発でベトナムで開発しているヒトに仕様や実装の方針を伝えるときにやってみた話をお伝えします。

draw.ioで仕様書を書く意味って何?

それぞれの職場で各々仕様書の書き方は違うと思います。私の職場でもそれまでやってきた方法がありました。ただ、様々な書き方はあったとしても大抵の仕様書は文字でなんとか説明しようとしているものが多いと思います。

文字ベースの伝え方は人によって書き方がぶれたり、伝え漏れが発生してしまう事が多いです。どうにかそういった情報の伝達ミスを解決できないかなと思っていったときに最終的にいきついたのがdraw.ioで仕様を作って渡すという方法です。

なぜdraw.ioで仕様書を書こうと思ったのか

draw.ioは自由帳のようなもので、UMLであれば大抵のものはかけますし、簡単なER図なども書くことができます。ただそれだけではdraw.ioで簡単な仕様書を作ろうという考えには至りませんでした。

draw.ioで仕様書を書いたらいいのではないかと思うようになったのはRDRA2.0の勉強会に参加したことがきっかけでした。

RDRA2.0とはなにか?

RDRAはRelationship Driven Requirement Analysis(リレーショナル駆動要求分析)と言われています。特徴をいくつかピックアップしてご紹介します。

ユースケース図を複数書く
複数書いたユースケース図の中で共通で使用するアイコンを決めて参照されたアイコンが一覧できる。
複数書いたユースケース図を関連付けて参照できるので読み手が文脈を補完できる

最大の特徴は、複数のユースケース図に関連をもたせてドキュメントを作成するということです。

関連をもたせてユースケース図を見ることによって、一つのユースケース図では表現できなかった背景や文脈などを読み取ることができます。

ユースケース図に関連をもたせるツール

ユースケースに関連を持たせるための仕組みを実現するためにはツールが必要です。

  • EnterPriseArchitect
  • Power Point

この2つがよく紹介されるようです。ただ、私が参加した勉強会ではFigmaとInstance Finderというプラグインが一番使いやすそうでした。

RDRAの書き方を採用するのであれば、それらのツールを使うのがいいのかもしれませんが重要なのは次の点です。

  • ユースケース図をかけるツールであること
  • 図を関連付けるくらいに自由であること

この2点を満たすことで、複数の図の関連を示すことができるのでそういった無料のツールが無いのかと考えていると普段使っているvscodeのdraw.ioで大体の要件が満たせることがわかってきました。

draw.ioで仕様書を書いてみる

次のようなケースで仕様書をオフショア開発しているヒトに渡す必要がありました。

一覧ページで使用しているAPIの改修

例えば、一覧ページに付属で情報を出したいという要件があったとします。言葉ですべてを説明すると難しいけれど次の図を組み合わせた仕様書を渡すとします。

どうでしょう。言葉は少ないのですが、だいたいどう実装をしたらいいのか具体的に思い浮かぶのではないでしょうか?もしこれがER図がなければデータ構造を自分で調査するヒトも居ると思います。API Responseがなければ、遅延読み込みで作ろうとするヒトも居ると思います。

このようにいくつかの図を組み合わせることで、少ない労力でもエンジニア - エンジニア感では余すことなく情報を伝えることができます。

まとめ

仕様を文字ベースで全て伝得ようとするヒトはいるのですが、それを読み解くのも大変ですし、コミュニケーションロスが発生するかもしれません。それよりだったら、簡単に図を書いて組み合わせることでエンジニア感での仕様書はかなりのコミュニケーションコストを削減する事ができると思います。

うまく運用で来たらまた追記します。

Discussion

ログインするとコメントできます