Markdown
Excel
設計書

設計書は Excel だけじゃなくて Markdown も使ってほしい

設計書の不具合を見つけるたびに 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 三つの設計書が存在しています。それぞれ概要、テーブル、ワークフローを記載しています。(左側が中身のテキストで、右側がプレビューです。)

https://gyazo.com/86a835cfe0233fb8cf4119e821d7e1ce

課題内容

テーブル excel_tablemarkdown_table に変更します。

対応内容

ディレクトリ内のファイルに対して excel_table を検索します。

https://gyazo.com/490797a107c71c27396a0f50c63fac5d

内容を確認した結果、今回は一括で置換するのがベストなので markdown_table に置換します。

https://gyazo.com/561737756342d5b3ee2b55bac2a50b84

変更内容をコミット(プッシュ)します。

https://gyazo.com/d37feaf4b22c42f4c82b0d4a3a28681c

対応確認

A C 二つのファイルが正しく変更されていることを確認します。コミットログを見れば他の人が確認することも簡単ですし、やっぱり元に戻すなどといった対応も直ぐに実施できます。

https://gyazo.com/6918d0bc0b53eeadb59910ddbafd092c

備考

今回使用したツールなどは下記の通りです。

  • エディター:Visual Studio Code
  • バージョン管理:Git
  • Git クライアント:SourceTree