マークダウンで書く必要性
職業としてソフトウェアを書くには仕様書が必要です。ジョエルのいう機能仕様書でもなんでも良いですが、ソフトウェアには動きを定義した文書が必要なことは皆さんもご承知のとおりです。
現在、日本のソフトウェア開発現場では仕様書といえば未だにエクセルやワードをお使いの組織も多いと思います。特に企業が最近のツール導入に貪欲でなく、今までのやり方を重視してきた場合、その傾向が強いと思います。
この仕様書環境へマークダウンを持ち込むと、飛躍的に生産性が高まる可能性があります。たとえば仕様書がテキストファイル化されることでバージョン管理システム上での変更管理が容易になり、GitHubのようなプルリクエスト型の業務フローと連動できます。Jenkins等の自動化システムとの相性も高まります。
エクセルやワードを使いつづけることによって、生産性を向上する機会を逃している可能性があります。ありがちな症例を以下にまとめてみます。皆様の職場はどちらでしょうか。
| シーン | エクセル、ワードの仕様書 | マークダウン仕様書(HTML) |
|---|---|---|
| 変更管理 | 変更管理ページを設け記載するため、変更記録に抜け漏れが発生する | バージョン管理ツールにログとして記載するため変更に抜けがない |
| 差分 | とれるツールもあるが良くわからない | Diffで明確にわかる |
| 修正点の指摘 | 指摘リストのエクセルなどを作り、担当が修正し、再度確認を行っている。 | プルリクエストで第三者も容易に修正提案ができ、マージを終了した時点で修正が完了し、再度確認をする必要もない。 |
| 仕様書参照 | 技術的には可能だが運用されていないため、毎回文書を開き直し、該当箇所を探している | 相互にリンクを貼ることが当たり前になっていて、問題の箇所がすぐに見られる |
本稿で行うこと
本稿での仕様書については、USDMという仕様書の書き方、考え方に則った仕様書をマークダウンで書くことを取り上げます。USDMはアプリケーションで行って欲しいこと、つまり「要求」があり、それに紐付いてアプリケーションの振る舞いを特定する「仕様」があると考え、要求仕様書を記述する方法です。抜け漏れのない品質の高い仕様書を作成できます。（なお、USDMについては末尾の参考資料をご参考ください。）
なので、本稿では仕様書をマークダウンで書くということは「要求」や「仕様」をどんなマークダウンで書くか？という問題として扱います。もちろん、それ以外の仕様書の書き方でも、ちょっとした工夫で対応できると思います。
仕様書をマークダウン化してみる。
要求と仕様とマークダウンに次のような一定の関係を持たせるだけで、要求仕様書をマークダウンの文書に置き換えることが可能です。
| USDM要素 | マークダウンに対応させた書き方 |
|---|---|
| 要求 | # [要求識別番号]要求内容 |
| サブ要求 | ## [要求識別番号]サブ要求内容 |
| 要求の理由/説明 | 要求の下にテーブルを作成 |
| 仕様グループ | <仕様グループ内容> |
| 仕様 | * [仕様番号]仕様内容 |
USDMでの要求仕様書事例を使うと以下のようにかけると思います。
# [pot-210] コンセント抜き差しで、ポットを利用できない/利用できる状態にする。
|要求の補足|内容|
|:---|:---|
|理由|特別なハード部品なしに利用できない状態/できる状態にした。|
|説明|２．１章～５章は、コンセントを差し込んでいる時の要求仕様である。|
* [pot-210-11] コンセントを差し込むと、設定値にはデフォルト値がセットされ、ポットが機能する状態（アイドル）になる。【説明】各要求に対する仕様の＜デフォルト＞を参照。
* [pot-210-12] コンセントを抜くと、ポットは蓋の開け閉め以外は何も機能しなくなる。
# [pot-220]アイドルの状態で、蓋を閉じたら、水位を確認し、条件に合えば沸騰行為をする。
|要求の補足|内容|
|:--|:--|
|理由|蓋を閉めるという行為で加熱（沸騰）の指示をしたい.|
|説明|沸騰行為の詳細は、３章の「温度制御行為」に記載する。蓋センサがonになって3sec経過するのを待つ理由は、注水やポットの移動の直後に、水面が波打っている状況が考えられるので、水面状態が安定する時間を想定したためである。|
＜蓋「閉」を確認する＞
* [pot-220-11]蓋センサが3sec以上onとなったら、蓋が閉じられたと判断する。
マークダウン化した結果
上記のように記載した場合、以下のようなマークダウン仕様書が作成されます。特に拙作のSunny Place Editorをお使いの場合、各要求や仕様にリンクが自動的に埋め込まれ、非常にスムーズに仕様や要求に参照できます。（って、いつまで更新をサボっているのかと。。。）
[pot-210]コンセント抜き差しで、ポットを利用できない/利用できる状態にする。
| 要求の補足 | 内容 |
|---|---|
| 理由 | 特別なハード部品なしに利用できない状態/できる状態にした。 |
| 説明 | ２．１章～５章は、コンセントを差し込んでいる時の要求仕様である。 |
- [pot-210-11] コンセントを差し込むと、設定値にはデフォルト値がセットされ、ポットが機能する状態（アイドル）になる。【説明】各要求に対する仕様のデフォルトを参照。
- [pot-210-12] コンセントを抜くと、ポットは蓋の開け閉め以外は何も機能しなくなる。
[pot-220]アイドルの状態で、蓋を閉じたら、水位を確認し、条件に合えば沸騰行為をする。
| 要求の補足 | 内容 |
|---|---|
| 理由 | 蓋を閉めるという行為で加熱（沸騰）の指示をしたい. |
| 説明 | 沸騰行為の詳細は、３章の「温度制御行為」に記載する。蓋センサがonになって3sec経過するのを待つ理由は、注水やポットの移動の直後に、水面が波打っている状況が考えられるので、水面状態が安定する時間を想定したためである |
＜蓋「閉」を確認する＞
- [pot-220-11]蓋センサが3sec以上onとなったら、蓋が閉じられたと判断する。
まとめ
本稿ではUSDMという仕様書の書き方を例にとって、マークダウンへと変換する一例を書きました。皆さんの工夫で、皆さんの仕様書も意外と簡単にマークダウンに変更できるのではないかと思います。
(参考)USDMの参考資料
要求を仕様化する技術・表現する技術USDMを発案された清水吉男さんの書籍です。