エムスリーキャリアでWebエンジニアやっている諸岡(morooka_cube)と申します。現在は薬局向けBtoBサービスのリニューアル案件に携わっています。
先日、開発ツールのレビューサイトFindy Toolsにて、データ基盤構築ツールTROCCOの記事を寄稿しました。
データ転送ツールtroccoのレビュー記事書きました！開発現場でバリバリ使ってます🛒
— もろーか (@morooka_cube) 2024年4月2日
trocco®の導入効果をレビューでご紹介(エムスリーキャリア株式会社-morooka_cube) https://t.co/RfhqqMBN2Y@findy_tools @primeNumberinc
最近のマイトレンドはHotwireとdbtとショッピングモール巡りです。
休日のプライベートな作業や情報収集する時、自宅だと捗らないという方いませんか？そんな時の気分転換にショッピングモール巡りがおすすめです！
（このブログもショッピングモール巡りがてら「スタバでマック」スタイルで書いてます）
ドキュメント化に取り組む以前の状況
私自身、ドキュメント化に対しては消極的な姿勢でした。
- 実装スピードに自信があり、かつドキュメント化は面倒で時間のかかる作業と思い込んで相対的にドキュメントを軽視していた
- Word・Excelで書かれた網羅的なドキュメントに対するアレルギー反応
- ドキュメントが効果的に働いているプロジェクトに関わったことがなかった
等が要因として挙げられます。要するに私もドキュメント作成が苦手です！！！
そして現在担当しているサービス自体もこのような状況だったので、リニューアル案件を進めるにあたり以下の課題が発生していました。
- ビジネスロジックのあいまい化・複雑化
- 関係者間のコミュニケーションコスト増加
- リニューアル案件に際しビジネスサイド・エンジニアともに関係者を増員
- 複雑なビジネスロジックのキャッチアップに追われる
- 既存メンバーであっても誤解や要件漏れを起こすため、コミュニケーションの齟齬原因に
- 要件定義・仕様設計の手戻り
- 現状仕様の理解が浅い・共通認識が取れていない状態で要件定義・仕様設計
- 実装フェーズに入ってようやく考慮漏れに気付き、要件定義のやり直し
- 最悪のケースとして「これは特殊パターンだから設計変更ではなくコーディングの工夫で乗り切ろう」でバグの温床に
- 既存機能に関しても穴が見つかり、「スコープ広げてイチから再設計したほうがいいのでは？」なんてことも
ドキュメント化に向き合ってみて得られたこと
ドキュメント手法に対する「食わず嫌い」状態から、見様見真似でやってみたところ以下のような効果が得られました。
- 関係者間コミュニケーションの改善
- チーム内や関係者間のコミュニケーションがスムーズに
- 要件や仕様の誤解防止
- 要件定義の進捗改善
- ビジネスロジックの解像度向上・簡素化
- 手始めに現行機能のロジックや業務フローを文書化してから「どのように追加するのがベストか」ベースで検討
- ロジック・業務フローの複雑化を防止
- 検討した結果既存ロジック・業務フローに変更を加えることになっても、関係者への周知が簡単に
ドキュメント化のフレームワーク・ベストプラクティス
アジャイルソフトウェア開発宣言「包括的なドキュメントよりも動くソフトウェア」
はじめてこの文書を読んだ時、私は「なるほど、ドキュメントも大事だけど動くソフトウェアのほうが大事なんだな。ドキュメント化には消極的な姿勢のままで問題ないか」程度の浅い理解でした。
今は別の視点で解釈しています。
「包括的なドキュメント」とは読み手の対象（経営層だったり新人プログラマーだったり）に関わらず理解できるよう情報が網羅された文書のことであり、関係者とのアジャイルなコミュニケーションができているのであれば、読み手の対象を絞った上で包括性を欠いてもよいと理解しました。
そして、アジャイルコミュニケーションの外野にいるステークホルダーに対しては、ドキュメントの納入ではなく「動くソフトウェア」を開発進捗のエビデンスとするという価値観です。
ドキュメントの網羅性は関係者とのコミュニケーション密度によって変わる
上記アジャイル開発宣言の解釈を前提とすると、「アジャイルなコミュニケーション」の実現具合によってドキュメントの適切な網羅性が変わることになります。
ビジネスサイドとの関係性ができていないプロジェクト初期は「言った・言ってない」を文書化する作業に追われるかもしれないし、逆に全ての意思決定を対面会話で済ませるほど密結合にコミュニケーションしているなら、会話の結論をメモするだけで済むかもしれません。
つまり、「ドキュメントのフォーマットを固定化するのではなく、コミュニケーション密度に応じてフォーマットを柔軟に変える」という考え方です。
状態遷移図・状態遷移表
ここまでマインドの話中心になってしまいました🙇♂️具体的な方法論も書きます！
先日社内のQAグループ主導でソフトウェアテスト手法の講座があり、その題材がソフトウェア設計・ドキュメント化の観点からもとても参考になったのでシェアします。
状態遷移図を書くと、「状態」と「トリガー（イベント）」で考慮漏れや不整合がないか整理することができます。
また、「遷移前の状態」、「トリガー」と「遷移後の状態」の関係を表した状態遷移表を書くことで、あいまいな仕様や認識の齟齬を生みやすい箇所を特定することができます。
講座の中では、この状態遷移図・遷移表に以下機能を追加する演習を行いました。
「承認済み」を「再編集」することで「未申請」にすることができる
「承認済み」を再編集で「未申請」にした場合のみ以下の動作とする
・「取り消し」で「承認済み」に戻る
・「申請中」に進んだ後も「未申請」に戻れば「取り消し」可能
・「取り消し」後の申請内容は再編集前の状態に戻す
…文章のみだとなんだかよくわからない印象（＝ビジネスロジックの解像度が低い）ですが、状態遷移図に起こすことで、「再編集」・「取り消し」というトリガーを実現するために「再編集・未申請」「再編集・申請中」という新たな状態が必要になることがわかります。
（「再編集・未申請」の場合は取り消し可だが、再編集ではない「未申請」の場合は取り消し不可とするため）
システム間連携時のフローチャート
システム間のデータ連携を行う機能を開発する際は、
- 私「処理Aは対向システムがやると思ってた…」
- 対向システム担当「処理Aはそちらがやると思ってた…」
のような認識齟齬を防ぐため、対向システムとの責務分けを明確にする必要があります。
そんな時はフローチャートを書いて「この処理は対向システムの責務」と明記するとわかりやすいです。
生成AIの活用（情報求ム）
フレームワーク・ベストプラクティスを駆使しても、ドキュメント化は時間がかかります。
大枠を自分でプロットした上で、面倒な作業は生成AIにお任せできるといいのですが…このあたり私はまだ試せていないので、情報提供お待ちしています！
終わりに
ドキュメント化、こわくないよ！！
