みなさんはドキュメントを書くとき、普段どのようなツールを利用することが多いですか？
私はシステム開発の現場でプロジェクトマネージャーをしていますが、これまで担当したほぼすべてのプロジェクトでWord／Excelを使ってきました。
ところが最近は、現職がクラウドサービスを開発・運営するFintech企業に勤めていることもあってか、社内向けドキュメントのほとんどはマークダウン（Markdown）記法になりました（残念ながら、金融機関との協業施策などで社外向け資料におけるWord／Excelの地位は揺るぎません……）。
本記事は、マークダウン記法のドキュメンテーションから私が受けている恩恵や、マークダウン記法の書き方などについてお話しします。
１．私がマークダウン記法で書いているドキュメント
「マークダウン記法のドキュメントを書きまくっているといっても、Design Docくらいでしょ？」
いえいえ、私がマークダウン記法で作っているドキュメントは、システム開発からプライベートまで多岐に渡ります！
実例をご紹介しましょう。
(1) 開発ドキュメント
- Design Doc（システム開発におけるエンジニアサイドの設計ドキュメント）
- README（GitHubでツールの使い方やインストール方法を書いたドキュメント）
- 開発方針書（外部に開発を委託する場合）
- サービス概要書、要件定義書の下書き
- RFP（提案依頼書）の下書き
(2) コンテンツ作成
- コンサルタント業務で作るスライドの内容
- Web記事原稿の内容
- Qiitaの記事
- 自己紹介文の内容
(3) タスクリスト
- 当月生産計上のタスクリストと実績
- 引っ越し手続きのタスクリストと実績
- 確定申告のタスクリストと実績
- 役所関係の手続きのタスクリストと実績
２．マークダウン記法で書く私にとってのメリット・デメリット
私がとても気に入っているマークダウン記法を使うことで、プロジェクトマネージャーやエンジニアは、システム開発の現場で多くの恩恵を受けることができます。
私がマークダウン記法で書きまくる理由を開発ドキュメント／コンテンツ作成／タスクリストそれぞれについてご紹介したいのですが、その前に、マークダウン記法でドキュメンテーションするメリット（それと少しだけのデメリット）を、私の独断と偏見で整理しました。
メリット
- 入力はテキストエディタなので動作が軽い。次々と思いつくアイデアを軽快に書き込むことができる。
- 分かりやすいルールに従って記入できる。テキストのメモであっても表現が統一されていて読みやすい。
- テキストベースのファイルなので、WindowsでもMacでも容易に扱うことができる。
- テキストベースのファイルなので、バージョン管理ツールで前バージョンとの比較を容易に行える。
デメリット
- デザインを反映させる（HTML文書へ変換）には専用のツールが必要。
- 協業先などの外部と共有するときはWordに清書する手間がある。
動作が軽いことは私にとって特に重要です。WordやExcelを使っているときに、急に処理が重くなったり挙動がおかしくなったりして、強制終了した（保存していないのに！）経験はありませんか？ 動作の軽いテキストエディタであれば、そのようなことはほとんど起こりません。
３．私が開発ドキュメントをマークダウン記法で書きまくる理由
システム開発をスムーズに進める秘訣は、チームメンバーの意識を合わせることです。誰かに何かをお願いする場面や、打ち合わせで決まったことを共有する場面など、プロジェクトマネージャーである私は、ステークホルダーとのコミュニケーションを必ずドキュメントをベースに行います。
「なぜ、マークダウン記法なのか？」
私にとっての価値は２つです。(1) 私は打ち合わせをしながらドキュメントをアップデートします。打ち合わせ中は、そのドキュメントを参加者に見えるように大型モニターに表示します。動作が軽快でないツールを利用すると、打ち合わせのリズムが悪くなります。テキストエディタは、打ち合わせのリズムを崩しません。
(2) 打ち合わせの只中に美しい見出しや段落を作るのは、手間がかかることです。内容を後から振り返るときや、打ち合わせに参加していないメンバーが読むときには、整った文書になっているといいですよね。マークダウン記法のルールに従って書いていれば、見栄えのよいHTMLになります。
マインドマップなどのツールも試しましたが、私にとって上記の要望に答えるツールはマークダウン記法でした。
見出しと段落について、マークダウン記法での書き方をご紹介します。
マークダウン記法
見出し
# 見出し１
## 見出し２
### 見出し３
#### 見出し４
##### 見出し５
###### 見出し６
※ HTMLのh1からh6タグに相当
段落
空白行を追加
※ HTMLのpタグに相当。なお、改行（brタグ）はスペース２つ
４．私がコンテンツをマークダウン記法で書きまくる理由
ITコンサルタントをしていたころ、PowerPointによる企画・提案スライドの作成は日課でした。コンサルで大切なことはスライドの見栄えではなく中身ですが、最初からPowerPointで書き始めると、必要以上に見た目に凝り始めてしまう癖がありました。これでは時間がいくらあっても足りません。
そんなときにたどり着いたのが、マークダウン記法でした。
「なぜ、マークダウン記法なのか？」
私にとっての価値は３つです。(1) 見た目に凝り始めてしまう癖があるので、見た目を容易に操作できるツールは避ける必要がありました。
(2) 表や参照サイトへのリンクを書くことが多かったので、記述ルールが必要でした。
(3) 企画・提案スライドに清書するときに、下書きがキレイに表示されることが必要でした。
PowerPointにはノートを書くスペースが用意されています。マークダウン記法で作成したファイルを別途用意することもありますが、PowerPointのノートにマークダウン記法で書くこともあります。
表とリンクについて、マークダウン記法での書き方をご紹介します。
マークダウン記法
表
|q|w|e|
|-|-|-|
|a|s|d|
※ １行目がヘッダー行、２行目で左寄せ「:-」、右寄せ「-:」、中央寄せ「:-:」の指定が可能
※ HTMLのtable, tr, th, tdタグに相当
リンク
HTMLのaタグに相当
５．私がタスクリストをマークダウン記法で書きまくる理由
以前私が勤めていた会社では、毎月の生産計上という作業が最も重要な仕事でした。
設計審査 ➡ 出荷検査 ➡ 部長確認 ➡ お客様確認 ➡ 検収 ➡ 生産計上
毎月の生産計上をクリアするためには、これらのタスクを順番に漏れなく実施する必要がありました。また、各タスクには期限（日時）が決められており、どれかのステップが期限に間に合わなければ、生産計上にたどり着けませんでした。
また、日常生活においてもタスク管理することは多々あります。
引っ越しに伴う住所変更は、電気・水道・ガス、銀行やクレジットカード、買い物サイト等々、いつも苦労します。漏れなく対応する必要がありますし、それぞれ手続きがバラバラで個々に調べるのはたいへん手間です。
このような場面で活躍するのがタスクリストです。私はタスクリストをマークダウン記法で作成します。
「なぜ、マークダウン記法なのか？」
私にとっての価値は３つです。(1) テキストベースでも見やすい記述ルールで、インデントを付けながら箇条書きを書くことができます。
(2) 箇条書きで、番号付きリスト（1. 2. 3. …）を作ることができます。
(3) 箇条書きで、チェックボックスを作ることができます。
私は先日、１年ぶりに引っ越しをしました。前回の引っ越し手続きのタスクリストを引っ張り出し、ファイルをコピーして今回のタスクリストとしました。
前回記入したチェックの解除も簡単です。Excelのフォームコントロールでチェックボックスを作るととチェックの解除に手間がかかりますが、マークダウン記法はテキストベースなので一括置換でチェックの解除が終わります。
引っ越しで必要なすべての手続きが一目瞭然で、スムーズに漏れなく手続きを進めることができました。
箇条書きとチェックボックスについて、マークダウン記法での書き方をご紹介します。
マークダウン記法
箇条書き
– 果物
– りんご
– バナナ
– 動物
– キリン
– ゴリラ
※ タブでインデント
※ 番号付きリストにする場合は「-」の代わりに「1.」を利用する
※ HTMLのul, ol, liタグに相当
チェックボックス
– [ ] チェックなし
– [x] チェックあり
※ HTMnput type=”checkbox” に近い（相当するHTMLタグがないため未対応のツールがあります。この記法が利用可能なGitHubとQiitaでも表示の仕方が若干異なります）
6. まとめ
ドキュメント作成のツールは巷にたくさんありますが、職場では慣例に従ってツールを選択することが多いのではないでしょうか。
ルールでクラウドサービスを使うことができないチームもありますよね。また、UMLやマインドマップといった図をベースに、チームメンバーとコミュニケーションすることが大切だとしているチームもあるかと思います。
マークダウン記法によるドキュメンテーションは万能ではありませんが、みなさんがツールを選ぶときの参考になれば幸いです。
