設計書の不具合を見つけるたびに Excel の設計書を綺麗に直しながらコーディングしろって？時間がいくらあっても足りないってばよ…。
という状況を経験した SE の皆さんは多いはず。ここで Markdown の出番です。まず初めにそれぞれのメリットを見ていきましょう。
Excel
- 画像や表、グラフなどが簡単に作成できる
- 関数やフィルターが使える
- 納品しやすい
Markdown
- メンテナンスがしやすい
- 文字を書くのに時間がかからない
- 検索がしやすい
メリットの詳細
一つ一つメリットを掘り下げて見ていきます。
Excel
画像や表、グラフなどが簡単に作成できる
Excel での画像の貼り付けはコピペで一発。表はセルの設定で直感的に作成可能。チャートなどのグラフは標準機能から適当に探して使うだけで綺麗なものが完成します。
一方、Markdown で画像を使用する場合はまず画像をファイル保存してからファイルへのリンクを記載する必要があります。表はテキストベースのため非直感的。何れも書きやすくしてくれる物があるので、書いてみて慣れなかったら使用してみるのもありだと思います。
関数やフィルターが使える
Excel では合計値や平均値を出したり、ある条件に当てはまるデータのみ抽出するフィルター機能がとても強力です。設計書ではあまり使用しませんが、いざという時にあるとやはり頼もしいです。Markdown はどちらも使用できません。
納品しやすい
現場は Excel などの Office 形式で納品することが多いです。Office で納品を求められた場合、Markdown で作った物は変換作業を挟まなければなりません。
Markdown
メンテナンスがしやすい
Markdown 最大のメリットです。Git などのバージョン管理を使用できるので、それを前提に説明します。バージョン管理を使用するとコミットログから変更が追える。複数人で編集可能。マージもわかりやすい。製品リリース後もコードの変更とともに適切なメンテナンスをしていけば、後から入ってくるメンバーにもフレンドリーです。
Excel だとバージョン管理を使用できません。正確に言うと使用できるのですが、変更箇所がわからないし、複数人でメンテナンスをしてたら 100% コンフリクトします。なのでどこかの共有ディレクトリに置いて運用する形が多いです。
文字を書くのに時間がかからない
Markdown はテキストを書いているのとほとんど変わらないです。好きなエディターを使用できるし、文字の検索やフォーカス移動などもやりやすいです。Excel だとセルを編集モードにして書く必要がありますし、方眼紙などにして綺麗にレイアウトしていると、改行なども考えながら文字をかかなければいけません。
検索がしやすい
Markdown の中身はあくまでテキストのため、フォルダ指定などで中身を一括して検索することが可能です。例えばテーブル名などが変わって設計書をメンテナンスしなければならない場合、エディターなどを使用して一括置換が可能です。Excel でも似たような機能を持った別のアプリケーションを探すかマクロを作れば可能です。
Markdown を使ってみる
最後に Markdown を使って設計書のメンテナンスをしてみようと思います。「開発を進めていく中でテーブルの名前が変わってしまった」という例題に沿って進めていきます。
設計書構成
A B C 三つの設計書が存在しています。それぞれ概要、テーブル、ワークフローを記載しています。（左側が中身のテキストで、右側がプレビューです。）
課題内容
テーブル excel_table を markdown_table に変更します。
対応内容
ディレクトリ内のファイルに対して excel_table を検索します。
内容を確認した結果、今回は一括で置換するのがベストなので markdown_table に置換します。
変更内容をコミット（プッシュ）します。
対応確認
A C 二つのファイルが正しく変更されていることを確認します。コミットログを見れば他の人が確認することも簡単ですし、やっぱり元に戻すなどといった対応も直ぐに実施できます。
備考
今回使用したツールなどは下記の通りです。
- エディター：Visual Studio Code
- バージョン管理：Git
- Git クライアント：SourceTree