システム設計の基礎：外部設計で作るべきドキュメントを考える
システム設計の基礎を学ぶ研修に会社のお金で行かせてもらったので、成果を書きます。
今回のテーマ
外部設計で作るべきドキュメントとはなにか？
研修の内容を受けて、外部設計段階で作成する一般的なドキュメントをまとめました。
それに対し、自分の開発チームがいま作っている資料を一般的なドキュメントの内容と比較・対応させて、外部設計にどんな資料が必要なのか考えました。
設計の前に：要件定義の確認
要件定義のアウトプットとして作成されるドキュメントは以下のようなものがある。
- データフロー図（DFD）
- 業務フロー図
うちだと、要件を文章や図で書いたものと業務フロー図がサービス仕様書に表現されているはず。このサービス仕様書を最初のインプットとして外部設計を作成し、業務設計担当者との認識を合わせていく。
まずは要件定義の確認、サービス仕様書を読む。チームで読み合わせとかすると良い。足りていない部分があれば要件定義した人に聞いてみる。
特に非機能要件、性能やSLAは設計に影響するので注意。
要件に書ききれていない非機能要件を聞き出せるのが良いエンジニアとのこと。
外部設計資料の一覧（一般）
世の中にはいろんなドキュメントがある
研修で習った各ドキュメントの名称と、表現したいことを簡単にまとめる。
コンテキスト図
- 開発領域、スコープ
- 関連システムの洗い出し
システム階層図
- ユースケース
- 機能の一覧
用語（ドメイン）一覧
- 用語の標準化
- 用語の定義
論理データモデル
- データ項目
- データの関連性
システムフロー図
- データと機能の関係
- 機能の処理順序
機能仕様書
- 機能の詳細（Input, Process, Output）
- 人とシステムの区別
機能/エンティティマトリックス
- 機能に対する各エンティティのCRUD
エンティティ仕様書
- データ項目の属性、桁数、制約（NOT NULLとかUNIQUEとか）
非機能要求仕様書
- 非機能要件の詳細
（うちのチーム的に）必要な外部設計資料とは
ここからがサビ
自分たちが作っているドキュメントと、研修で習ったドキュメントとを繋ぐ。
システム階層図 -> API・バッチ一覧
単純に実装する機能の一覧。
資料として明示的に作らない場合でも、チケット管理ツールのエピック等で表現されてるイメージ。
用語一覧 + 論理データモデル（+ ちょっとコンテキスト図） -> ドメインモデル
ドメイン名は見ればわかる名前、そのものの本質を表す名前をつけるようにしている。そのため、用語の意味はドメイン名によって表現される。
通常ドメイン名はなるべくサービス仕様書に記述されている言葉を用いるので、その場合はサービス仕様書内で意味も定義されているはず。
システム的な都合で作成されたドメインの場合など、業務に現れないドメインの場合は、外部設計仕様書に別途記載する必要がありそう。
データの関連性は、モデル中の多重度、依存関係で表現される。
関連するサブシステムとの結合もドメインモデル中に表現している。
これらを書くことで、開発領域も可視化できる。
システムフロー図 + 機能仕様書 -> ユースケース記述・ロバストネス図
要求の機能をより具体的に落とし込んだドキュメントとして同じ位置だと考えた。 ユースケース記述は、文章でユースケース単位のInput, Process, Outputを表現できる。(≒ 機能仕様書)
ユースケース記述はロバストネス図のインプットになる。図にすることで、
- 人（アクタ）とシステム（エンティティ・コントローラ）の区別
- データ（エンティティ）と機能（コントローラ）の関係
- 処理順序
あたりが自然に表現できそう。
ユースケース記述とロバストネス図だと切り口がユースケースという視点になるけれど、
機能とデータと人、それぞれどう関係しているかを表す分には十分かなと思う。
もうちょいシンプルに機能とデータの関係を表した図をいつも書いていたけど、あれが何図なのかわからない （ずっとコンポ図と呼んでいたけど、ちゃんと調べたらなんか違う気がする…）。
機能・エンティティマトリックス -> 状態遷移表
- 特定のイベントが起きた場合のエンティティの状態
研修中はこれが似たような位置だと思ったけど、社内で聞いてみたら設計思想によって使い分けた方が良さそうという話になった。
弊社はイベントドリブンで作ってることが多いので状態遷移表をよく書いてるけど、
CRUDは外部のサブシステムの機能から呼ばれた場合とかも書ける。
なにかのイベントが起きたことを検知して自分の状態が変わるのが前者、
このエンティティはこの状態になれ！っていうのが後者の考え方。
たぶん。
ほか、普段あんまり作ってないもの
- 非機能要求一覧
- コーディング規約
非機能要件の確認は冒頭に書いた上に、最近はデザインレビューの項目でもあるので、設計の初期段階で明確に検討するべきなのだと感じた。抜けがち。
コーディング規約はうちのチームは放棄…わりと察する系（つらい）。
- エンティティ仕様書 -> テーブル設計（内部設計）
エンティティ仕様書は桁数とか制約も書くので、うち的にはテーブル設計だと思うんだけど、
このあたりまで外部設計の段階で書くものだとは思ってなかったので意外。
研修中でも物理データモデル設計は内部設計側にあるので合ってるんだけど、たとえばユニーク制約とか貼ったら、このデータはユーザごとに一意なんですとか、
そういうレベルの話は要求者側に認識してもらっても良いのかもな〜と思った。
まとめ：外部設計ではどんなドキュメントが必要なのか？
結論、これを作れば設計はばっちりのはずだ！
- API・バッチ一覧
- 実装するものリスト
- ドメインモデル
- ユースケース記述
- ユースケース単位で必要な機能を洗い出す
- 機能の詳細を書く
- ロバストネス図
- 機能とデータと人の関係を書く
- 処理の流れを書く
- 状態遷移表
- 特定のイベントが起きたときのドメインの状態を書く
さいごに
この研修を受けた目的は、標準を知らない自分が、社外で標準的な開発プロセスを学んできた人と話せるようになることでした。
で、研修で世間の標準を学んでみてよかったことがあって、
「自分の中に標準があることの安心感、自信」
を感じられるようになったこと。
これまで外部設計も見よう見まねでこれがほしいあれがいるかもと付け足したり消したりしながら迷走していた状態だったのですが、
たとえば、これは外部設計で書くべきなんですか
（開発チーム内部で共有できていれば十分な内容なのでは？）という問いに対して、前は答えられなかったけれど、研修を受けてからは
「これは自分が勝手に言っているだけのものではない」「要求元に確認したほうが良い内容だ」「こういう内容が必要だ」
という裏付けがある状態になったので、多少自信を持って話せるようになった。
ある程度の現場経験を積んでから理論を学ぶと、ここで言われてることって今までやってきたあれなんだ！
というような気づきを得られるようになり、最近は読書もすごく楽しくなっているのですが、研修もとても良いインプットになりました。めちゃくちゃ忙しくて死ぬかと思ったけど本当に行ってよかった。
あと余談ですが最近ユースケース駆動開発実践ガイドを読んでるのでもろ影響されてる（ロバストネス図のくだりとか）。
以上、ここまでお読みいただきありがとうございました。
この内容に対する見解がありましたらぜひ教えてください。
社外研修にいこう
会社に行きたくなくなった日、反対方向の電車に揺られて向かうための海の用意がありますか？わたしはあります。どこかは秘密です。
昨日から明日まで3日間、社外の研修に行っています。システム設計の基本を学びに行っています。内容はまた研修が終わったら機会を改めてアウトプットをしたいと思います。
しかしなんというか世の中には色んな人がいるんだなあと思いました。そういう話をします。
研修の参加者は発注側と開発者のどちらもいます。混合でグループワークをしているので他の参加者の方々ともお話しするのですが、発注側のとある人がパンチ効きすぎていてすごい。もうこの人はすごいのでおじさんと呼びます。
研修中のわたしたちはもろもろ仕様書などを書いており、今日は状態遷移の線を一本引き忘れた仕様書を作成し隣のチームからのレビューでボコボコにされる楽しい演習でした。めちゃくちゃバグってるじゃんと笑っているところで、おじさんは言いました。
「これ書いたの誰？」
チームの成果物はチームの責任で作ったものなので、これは全員の責任ですからね！と反射的に大きな声が出て自分で焦りました。当たり前すぎて忘れていましたが世の中チームで働くという経験をしている人は少ないのですよね。いやまあそうですよね。冷静になればそうです。そんなこと言ってくるプロマネとかまじで嫌だなあとか絶対一緒に仕事したくないなとか思いましたが世の中そういうものなのかなと考えさせられました。
しかしおじさんは容赦なく畳み掛けてきます。「大きな指摘はなかったの？」「いや、今言いましたけどこの遷移がひとつ抜けていたんですよ」ここでおじさんは再び攻撃を繰り出してきます。
「なんだ。じゃあひとつ忘れただけ？」
いや結構ですよ、結構なバグですよ、その遷移をひとつ抜かしたせいで我らの設計したシステムは5000品目の商品を扱う発注システムで1品目ずつしか注文できないというすてきな仕様になっています。他のメンバーはちゃんとこの致命的バグを認識しているのに？このまま発注したら大惨事だけどその認識で本当にシステム開発を依頼する仕事をなさるのでしょうか？絶対一緒に仕事したくないなとか思いましたが世の中そういうものなのかなと考えさせられました。
社外を知るという目的は達成されたと感じています。文字通り知見が広がりました。世の中色んな人がいるんだ。べんきょうになるなあ。研修にいってよかったなあ。研修の後会社に帰ってきたら会話がつつがなく進んでいく環境に感動を覚えました。弊社はすごい！研修カリキュラムはまだあと1日残っていますが既にすごいおじさんと遭遇できているのでたいへん貴重な経験ができました！みんな社外研修に行こう！絶対に許すな！
良いチームは良いふりかえりから
今日は前向きに、ふりかえりについて書きます。
良いチームは良いふりかえりから
毎スプリントの終わりにやっている、ふりかえり。
その中で最近やってよかったことを紹介します。
（社内の開発チーム向けLTで発表した内容です）
agenda
ふりかえりは以下の流れでやります。
- Tryのふりかえり、エターナルキープ
- 今週の自分コーナー
- KPT（いつもの）
- Tryを朝会で毎日確認
1. Tryのふりかえり&エターナルキープ
KPTしても、せっかく出したTryするする詐欺になることがある。それはもったいないので、Tryをやりっぱなしにしないために、必ずTryのふりかえりをします。
- 先週出したTryはTryできたか？
- TryしたならProblemは解決したか？
をみんなで話し合います。
- よくなかったらやめる
- よかったら継続する（キープ）
- 意識しなくてもできるくらい身についたら、エターナルキープ(EK)へ移動
エターナルキープとは文字通り永遠のキープです。
そしてエターナルキープの数はチームが挑戦してきたことの数、チームが積み重ねてきた軌跡そのものです。
たまにまとめて見返すと、達成感でしみじみします。
2. 今週の自分コーナー
ただのKPTでは飽きてきたのでなにか新鮮味を、という時に出てきたTryのひとつ。
ふせんに「今週の自分」を絵で描いてひとりずつ発表します。
とてももりあがります。アイスブレーク的な立ち位置です。
ここで書くのはなんでもあり。人物画から抽象画まで個性が際立つ。内容もプライベートなこともOKとしているので、個人のことをよく知れてコミュニケーションのネタにもなったり。
基本的にワイワイ楽しくやります！
3. KPT（いつもの）
ここからいつものKPT。ですが良いチームのふりかえりはここが違う。
- Keep：みんなで喜ぶ
- Problem：みんなで反省する
- Try：チームで改善したいものをひとつ以上決める
- やる。で終わらないやつ
- みんなでやれるやつ
- やる気のあるやつ
良いチームではK/Pどちらもたくさん出てきます。特にK。その週にチームで起きたことをみんながわかってるから、他の誰かが出したKもPも自然に自分事になる。
そして最大のポイントはチームで改善したいものをひとつ以上決めることです。特に、誰かがやるのではなくチームとしてやることというのが大切です。
たとえば超具体的な例ですが、
- P：残業が多い。つらい→T：朝のうちに今日やることのゴールを決めておく。ここまで終わったら帰ろうの流れをつくる
- P：ベロシティを上げたい。モブプロ全員でやるのはちょっと無駄が多いのではないか→T：4人チームなので2人ずつのペアに分かれて作業してみよう
のような取り組みをしました。これももちろん前述のように、スプリントの最後にふりかえりして成果が出ているかどうかを確認します。
4. Tryを朝会で毎日確認
Tryするする詐欺になりがちなもうひとつの要因として、Tryを忘れる、一旦ふりかえりが終わったら次のふりかえりまで見直さない…というのがあると思います。それを改善します。
- 朝会チートシートに「Tryの確認」を入れる
- Tryできてるか、毎朝みんなで確認
できてると「おっTryできてるじゃん〜」て元気になれます。
毎日確認されるので、忘れてると思い出します。
最終的に次のふりかえりでまた確認されるので、これはやったほうがいい！と各々が思ったことは自然に取り組むようになったと思います。
まとめ
ふりかえり、ちゃんとやってますか？惰性になってませんか？ この中で自分のチームでも取り入れられそうな要素があったら、ぜひ取り入れてみてください。ふりかえりが面倒になってきたとき、なにかひとつ新しいことをやってみる、それだけでもチームの空気が変わるきっかけになると思います。
良いチームは良いふりかえりから！！！
良いチームを作っていきましょう！！！
心の余裕を持ちたい話
先週のHUGっと！プリキュア23話で「30過ぎた大人には仲間なんていない」と発言する敵キャラが現れて物議をかもしていましたが、心の余裕がないとこうなってしまうのかなあなんてそこにある程度の実感を伴ってしまうあたりがつらい年頃です。
忙しいと余裕がなくなる。
余裕がなくなって良くないことのひとつに、「自分はこんなにがんばってるのに」という意識で苛立ちが他責の方向に行ってしまうことがあると思う。
同じ案件に関わる人たちのはずなのに、自分の周りとそれ以外で線を引いてしまう。自分の内側、その線より向こう側が外側。
だんだんと外側の人や作業に対して「わざわざ時間取って○○したのに」みたいな意識が出てくる。
「自分の案件は忙しいのに」
「自分のチームは忙しいのに」
「自分は忙しいのに」
自分の内側にある範囲がどんどん狭くなっていって、関連するチームやチームメンバー、一緒にやっているはずの人たちのことまで外側においてしまう。
仕事が果てしなくうまくいっていないとき社会人歴2年先輩の友人に「自分以外の人が全員自分をバカにしているような気がしている」と相談したら2年前に通った道だと言われたことがあるので、大抵だれしもみんなこういうことがあるんだろうなと思う。
とにもかくにも、進捗に安心感があるかないかだけでこのへんの心の余裕は全然違ってくるので見積もりとリリースプランニングをやりましょう。考えて見える化しておけば不安もやわらぐ。見えないものが不安になる。見えるものは怖くない。
もういい大人なんだから感情的にならずに仕事したいと思うしなるべく笑っていたいと思うけど、どうしても余裕がない時は苛立ったりしてしまう。というか結構感情が出る方なので落ち着きたい。空気を悪くして良いことなんてひとつもないと頭ではわかっているつもりだけれども全然ままならない。
チーム崩壊の足音一覧
スクラムなチームをうまく作るための手法を考えていたのですが、残念なことに、逆にこれが起きるとチームとしてヤバいという知見のほうが溜まってきたので書きます。
チーム崩壊の足音一覧
今日は3つ書きました
1. 仕事がチケットで表現されていない
プロジェクト始まりたてのときとかリーダーの立場の人にありがち。決して働いていないわけじゃないというかむしろがんばって進めてるはずなのにバーンダウンしていない、あるいは何をしているのかわからないのに一日が終わってしまうという時はこれかもしれない。
解決策：見えないタスクをチケットにする
後から追加でもいいからやったことをチケットに表現する。ストーリーポイントを振る。やったことをチームメンバにアピールする。
2. 各々の仕事を分業しすぎ
わかりやすいのはコーダーと調整役とか。
進捗が差し迫っていると特に、つい得意分野ごとにタスクを振りがちになってしてしまう。
ただし、ここで分けすぎると自分の仕事の範囲を守りに入るので危ない気配がする。
チームの目的はサービスに必要なものを開発することで、個人のタスクが終われば終わり、ではない。チームはチームでいよう。
解決策：極力ペア作業で進めるようにする。
これだけでとりあえず個人の仕事という形はやめられる。
少なくともペアのメンバ同士では認識を合わせるためにコミュニケーションを取るので、なんとなく一体感が出てくる。 ペアをシャッフルしたり朝会もペアごとに喋ってもらったり、このあたりは工夫がいるかもしれないけど、この一体感をチーム全体まで広げられるとチームとしての体裁が戻ってくる。
リーダー的な立場からも、ペアごとにタスクをアサインされているので、全体のうち進行中のタスクの見通しがよくなる感じ。
3. デイリースタンドアップやふりかえりをさぼる
なんとなく朝会やってないとか。ふりかえりに活気がない、惰性でやってる、進捗やばいから今週はふりかえり飛ばそう、などなど……
解決策：やばくてもイベントは極力ちゃんとやる
今日中にリカバリしないと無理〜〜〜みたいなとき以外飛ばしてはいけない。今日がだめなら明日には絶対やろう。
実際にこれやってるときとやってないときを比較すると実感としてわかるんだけど、こういうイベントをちゃんとやるということは、やっぱり大事。アジャイル開発のパターンを崩し始めるとチームがけっこうヤバいなという感じがしてくる。
自分はスクラム開発のやり方しか経験してないので、元から周りがそういう活動をやってるのを見ようみまねでやってたけど、こういうイベントでチームの空気ができていくんだなあ、昔の人はすごいなあなどと思う。
以上です
いかがだったでしょうか。
これは実体験に基づく見解なので非常に局所的なものだとは思いますが身近なところでこういう傾向があるときは注意しましょう わたしも次回この傾向が出てきたら気をつけようとおもいます
と言いながらも今まさに全部にあてはまるとても危険な状態なので、ここに書いたとおりひとつずつ立て直して、なんとかチームになりたいと思います。
しかし二人チームというのは難しい……先述したチーム内ペアともちょっと違う感じがするので、二人でどうチームを作っていくかというのは次の課題。
自分で自分の機嫌を取る術
あー。最近いそがしいですね。仕事たいへんですね。
余裕がなくなると、イライラしたり悲しくなったり人への当たりが強くなってしまったりしてしまいます。そういう日が増えてしまって帰り道でひとり反省会しています。
そうやって感情に振り回されると余計に疲れる。ひとり反省会するのもまあまあストレスだし。情緒が安定してる方ではないので、そこそこ感情に振り回されています。
自分の面倒は自分で見ろよということで、自分の感情が荒れていることを感じたらそこに理由をつけよう、という話です。
これはしばらく前から下書きに置いてあったエントリなのですが、気持ちが全く追いついておらず最近はなにひとつできていないので自戒を込めて投稿します。
例えばイライラした時に
- 「自分はいまイライラしている」と気づく
- 「イライラしているのはなぜなのか」と考える
メタ認知というらしい。
メタ認知 - Wikipedia
まず「あーいま自分めっちゃイライラしてるわー」って頭の中で言う。そしてその感情に、自分なりの理由を見つける。
これやるだけでもけっこう楽になる。
「なんかイライラする」→「お腹すいているからかも。おやつ食べよう」とか。
「気分が滅入ってきた」→「そういえば昨日寝不足だった。諦めて今日は早く帰って寝よう」とか
「なんてことない指摘ですごく悲しくなった」→「ちょうど頑張ってた作業だから過剰に捉えちゃったな」とか
そういうかんじ。なんなら気休めでも良い。
あるいは
「いま人の意見をネガティブに捉えてるな」と気づいた上で
「新しいことをやる時に不安になるのはありがちな感情」とわかれば
「今までと違う、やり方のわからないことだからやりたくないって感じてるんだな。でもやる気がある人がいるし、挑戦してみても良いかも」とか、仕事の中でも感情から距離をとって冷静になることでうまくやれそうな気がしたりする。
楽に生きよう
意識が逸れやすい人間なので、理由つけて納得感が得られたりちょっと目の前ににんじんぶら下げたりするだけでも案外なんとかなってる。
世の中こういうのをみんな結構あたりまえにやってるのかもしれないけど、わたしは社会人になってからこういう技を得た。とにかく楽に生きたい。
