OutSystemsプロジェクトで使う設計書を考えてみる

OutSystems公式動画から作成する設計書を拾ってみる

OutSystemsの公式動画コースに、プロジェクトをどういう工程で進めていくかを解説するものがある（The OutSystems Method）。

その中で開発者がメインになるProject Deliveryの各工程と、それぞれで作成するとされている設計書は以下の通り。

開始前：Architecture Canvasを作成（アーキテクチャを決めておく）

開発中：動画内では設計書に言及無し

開発完了後、リリースまで：技術文書の最終版を作る（スライドEvents Calendarに含まれる線表の中で、OutDocとその他のドキュメントが挙げられている）

最終版を作るということなので、途中のドキュメントは必要に応じて開発中に作成しておくということだろう。わざわざ設計書を起こすまでもない内容であれば、設計書は作らず、リリース段階でOutDoc出力を取っておくだけでもよいという判断と思われる。

Architecture Canvas

OutSystems推奨のモジュールアーキテクチャ設計図法　兼　技法。

モジュール・アプリケーション・Teamをどう分割し、関連させるかの手順とルールをまとめている。

開発開始時にTech Leadなどが作成する。

Architecture Canvasを使った設計の骨格を参照。

Architecture Canvasについては、初期作成時だけでなく、アーキテクチャに影響を及ぼすような改修をするときも必須で作成しておいた方がよいと思う。

フォーマットは、ExcelやPowerPointで自作してしまえばよい。

OutDoc

OutSystemsによってサポートされているForgeコンポーネントでOutDocというものがある。

モジュールを指定すると、設計情報（ActionやEntityにどんなものがあるのか、などの一覧情報）を抜き出してドキュメントとして表示してくれる。

自動保存の機能はないが、Seleniumを使ってOutDocを自動出力したいで確認したように、外部のスクリプトを使うなどして自動化は可能。

注意点としては、全ての情報が取れるわけではないのと、取れる情報は定型的なものでしかないということ。

と、いうわけで、一定タイミングで、全てのモジュールについてOutDocで生成されるドキュメントを自動取得してバージョン管理システム等に保存しておくのがよさそう。

Design Document

The OutSystems Methodでも例として挙げられているだけで、このフォーマットで書かなければならない、というものではない。ただ、Design Docs at Googleというページの記述を見ると、OutSystems開発プロジェクトとしてしっくりくる設計書になりそうな印象。

以下で、上のリンク先をまとめつつ、OutSystemsを使った開発で作成する設計書について検討する。

Design Documentとは

プログラム作成前に作成される、ソフトウェア設計のドキュメント。

実装方針、設計上の意思決定を記述する。

非公式の色合いが強く、厳密なフォーマットは決まっていないとされている。しかし、以下のような内容が、項目の候補として（おそらくは経験的に）認識されている。

コンテキストとスコープ（これから作成するソフトウェアの簡潔な、概観とバックグラウンド）
目的と目的でないもの（ソフトウェアで達成するべき目標、および達成を目指さないこと）
設計（上2点を踏まえて問題を解決するソリューションを示す。また、その決定にあたって検討した代替案と選択した理由を示す）
- システムコンテキストダイアグラム
- API（I/Fの全項目を記述したりはしない。設計重要な部分のみ）
- データストレージ’（同上）
検討された代替案（選択されなかった設計の代替案を示し、どのような理由で現在の設計を選択したかを示す）
横断的な関心毎（セキュリティ、プライバシーなど、SIでは非機能要件と呼ぶもの？　設計が含む非機能要件上の懸念を挙げ、対処策を示す）

作るとしても、全開発で必須ではない

Design Documentはプロセスで、開発チームに作成を義務化するようなものではない。

また作成・レビュー・保守には時間と工数がかかる。

そこで、事前に設計情報をドキュメントにしてコンセンサスを得る、シニアエンジニアのレビューを経る、保守時に参照し設計意図や経緯等を知る、といったメリットがデメリットを上回るときのみ作成する。

Design Documentのフォーマットは厳密に決めるものでもないため、必要な項目のみ作成することも考えられる。

OutSystemsで作成する設計書案

まず、Design Documentは、設計において代替案の検討や事前調査が不要な、定型的な機能の開発には不要。定型的でない機能であれば、開発の前に作成し、シニアエンジニアやユーザーの代表者のレビューを得るようにしたい。

「Design Documentとは」に示した設計項目のうち、APIやデータストレージ（OutSystemsではEntity）は、UIと共にService Studio上でeSpace内に作成し、それをレビューする形にした方が楽かもしれない。もちろん、ユーザー等仕様決定権を持っている人がService Studioの使い方くらいは学習してくれる場合に限るが。

その条件を満たせず、仕様を決定／承認してもらう必要があるとなると、外部設計書を作成することになってしまい、作業工数は膨らみ、アジリティも落ちてしまう。できれば避けたい。