設計書や仕様書、みなさんは何で書いているでしょうか。Word、Excel、最近ならMarkdown。私も長いことこの3つのどれかでした。
ところがここ最近、私の現場ではHTMLで書くことが増えています。しかもこれが、思っていた以上に具合がいい。実際に開発以外の部署へ自社システムの仕様を説明する場面でHTMLの資料を見せたところ、「分かりやすい」と評判も上々でした。
この記事では、なぜ設計書・仕様書をHTMLで書くようになったのか、Word・Excel・Markdownと比べて何が違うのかを、実際のサンプル画面つきでまとめます。向いていない場面についても最後に書きます。
これまでの3つと、それぞれの困りごと
Word
設計書の定番です。ただ、複数人で触るとレイアウトが崩れる。図を1つ差し込んだだけで後ろのページが全部ずれる、あの現象です。
バージョン管理機能はありますが、一度前の版に戻すと、戻す前の状態には帰れないことがあります。「あの記述、やっぱり必要だった」となったときに詰みます。
Excel
表を書くぶんには最強です。項目定義やテスト仕様書はExcelが速い。一方で、印刷を前提にセル結合を重ねた資料は、あとから項目を1行足すだけで大工事になります。
Markdown
開発者にとっては書きやすく、Gitでの差分も見やすい。開発チームの中だけで完結するならこれで十分です。
問題は配布です。他部署や社外に .md ファイルを渡しても、相手はまず開けません。開けたとしても記号だらけの生テキストが表示されるだけです。GitHubやエディタで見てもらう前提が置けない相手には、そもそも渡せない形式なのです。
なぜHTMLなのか
1. HTMLファイル1枚で配布できる
「CSSはどうするの？」というのが最初に出てくる疑問だと思います。答えはHTMLの中に書いてしまう。<style> タグで <head> の中に書けば、外部ファイルは不要です。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>打刻機能 機能仕様書</title>
<style>
/* CSSはこのファイル内に全部書く。これで1枚のまま配布できる */
body { font-family: "Yu Gothic", sans-serif; line-height: 1.8; }
table { border-collapse: collapse; width: 100%; }
th { background: #eef3f9; }
</style>
</head>
これで spec.html というファイル1つをメールなりチャットなりで渡せば、相手はダブルクリックするだけで読めます。画像も data: URI で埋め込めば、本当に1ファイルで完結します。
2. Gitでバージョン管理できる
HTMLはただのテキストなので、差分が行単位で見えます。「前回のレビューから何が変わったのか」がプルリクエストで分かる。これはWordやExcelでは得られない体験です。
過去のどの版にも戻せて、戻したあとにまた進められる。ブランチを切って改訂案を並行で検討することもできます。バージョン管理の柔軟さでいえば、Officeの独自機能とは比較になりません。
3. 表現の幅が広い
ここがWordやMarkdownとの一番大きな差です。
- ページ内リンクが張れる
目次から各章へ飛べて、各章から目次へ戻れる - 別の文書や社内システムへのリンクも張れる
「詳細は要件定義書RD-002を参照」がクリック一つで開く - フォント・サイズ・色を自由に変えられる
必須項目は赤、任意項目はグレー、といった強弱がつけられる - 図や画像を挿入できる
画面レイアウトも処理フローも載せられる - 注意書きを枠で囲む、コード片を等幅にする、といった意味に応じた見た目を作れる
Markdownでも見出しやリストは書けますが、「この行だけ赤くしたい」「ここを注意ボックスにしたい」となると結局HTMLを書くことになります。だったら最初からHTMLでいい、という話です。
4. ブラウザさえあれば読める
相手のPCにWordやExcelが入っていなくても関係ありません。ブラウザは必ず入っています。
さらに、レスポンシブに作っておけばスマホでも読めます。「客先で仕様をさっと確認したい」「移動中に見返したい」といった場面で効いてきます。Excelの方眼紙をスマホで開いたときの絶望を思い出してください。
実際にどう見えるか
文章だけだと伝わりにくいので、架空の勤怠管理システムを題材にサンプルを作りました。HTMLファイル1枚、CSSは全部その中に書いてあります。
文書番号・版数・最終更新日といった管理情報を頭に置き、その下に目次。目次の各項目はページ内リンクになっていて、クリックすればその章に飛びます。各章の見出し横には「▲ 目次へ」を付けてあるので、行ったり来たりが楽です。
入力項目定義は表で、必須・任意は色分けしたラベルにしています。設計上どうしても外せない前提は黄色い注意ボックスに。処理フローはSVGの図で、これもHTMLファイルの中に直接書いているので画像ファイルは要りません。
そして同じファイルを、そのままスマホで開くとこうなります。
目次は1列に、横に広い表は横スクロールに切り替わります。ファイルは1つのまま、見る端末に合わせて形が変わる。これはWordやExcelにはできない芸当です。
前提を変えたのはAI
ここまで読んで「言いたいことは分かるが、HTMLを手書きするのは面倒では？」と思った方が多いと思います。まさにそれが、HTMLが設計書として普及しなかった理由です。
Wordなら見出しボタンを押すだけ。HTMLだとタグを書く。表を1行足すのに <tr> と <td> を並べる。この差は、資料を書く人にとって決定的でした。
その前提が、AIで消えました。「この表に『打刻場所』の行を追加して、在宅勤務のときは REMOTE と書いて」と頼めば、そのとおりに書き換わります。タグを書く手間がボトルネックでなくなった時点で、HTMLを避ける理由がほとんど無くなったわけです。
同じことを考えている人は他にもいるようで、SNSでも「設計書はHTMLでいいのでは」という話題を見かけるようになりました。
4つの形式を比べる
| Word | Excel | Markdown | HTML | |
|---|---|---|---|---|
| 表現の自由度 | ○ | △ | △ | ◎ |
| ページ内リンク・外部リンク | △ | △ | ○ | ◎ |
| Gitでの差分・履歴 | × | × | ◎ | ◎ |
| 社外・他部署への配布 | ◎ | ◎ | × | ○ |
| 閲覧に必要なもの | Word | Excel | エディタ等 | ブラウザ |
| スマホでの閲覧 | △ | × | △ | ◎ |
| 印刷・製本 | ◎ | ◎ | △ | ○ |
| 集計・計算 | × | ◎ | × | × |
こうして並べると、HTMLが不得意なのは集計・計算だけだと分かります。裏を返せば、数字を計算させる資料はこれからもExcelでいい、ということでもあります。
現場で使ってみた結果
先日、自社システムの仕様について開発以外の部署に説明する場面がありました。そこでHTMLの資料を画面に映して説明したのですが、これがなかなかウケが良く、「分かりやすい」と言ってもらえました。
理由を自分なりに考えてみると、次のあたりだと思っています。
- 目次から必要な章に飛べるので、説明の途中で「その話はここです」と即座に見せられる
- 色と枠で強弱がついているので、どこが重要かが説明しなくても伝わる
- 画面レイアウトの図が載っているので、開発の言葉が分からなくても実物のイメージがつく
- その場でリンクを送るだけで、相手も自分の端末で同じものを見られる
Excelの方眼紙を画面共有して、スクロールしながら「ええと、この行の…」とやっていた頃と比べると、説明のテンポがまるで違いました。
HTMLが向かない場面
とはいえ、何でもHTMLにすればいいわけではありません。次のような場面では、素直にWordやExcelを使ったほうが早いです。
- 納品物として体裁が決まっている資料
表紙・ヘッダーフッター・ページ番号・押印欄まで様式が指定されているなら、その様式に従うのが正解です - 印刷して配る前提の資料
HTMLも印刷はできますが、改ページ位置の制御はWordのほうが確実です - 計算させる資料
工数の試算、テスト結果の集計。これはExcelの独壇場です - レビューをWordのコメント機能でやる文化がある場合
ツールを変えると、レビューする側に負担が寄ります - HTMLファイルの添付が制限されている環境
セキュリティ設定でhtml添付をブロックする組織もあります。この場合はPDFに書き出すか、社内の共有ストレージに置いてリンクを渡すことになります
要は相手と目的で選ぶという当たり前の話で、HTMLはその選択肢のひとつとして、思っているより強い、ということです。
まとめ
- CSSをファイル内に書けば、HTML1枚で配布できる
相手はブラウザで開くだけ - テキストなのでGitで差分も履歴も残せる
Officeの独自バージョン管理より柔軟 - ページ内リンク・色・図・レスポンシブと、表現の幅がWordやMarkdownより広い
- これまで普及しなかった理由は「書くのが面倒」だった
AIがその前提を消した - ただし様式が決まった納品物、印刷前提、計算が要る資料は今まで通りでいい
設計書の形式は、その現場の文化や取引先の都合に縛られがちな領域です。それでも、自分の裁量で決められる資料が一つでもあるなら、次の1本をHTMLで書いてみると景色が変わるかもしれません。
次に読む記事
