目次
Markdownのメリット・デメリット
ワードやエクセルにもいいところがありますが、複数人で同じファイルを管理したり、仕様書などのようにバージョン管理されている文書に関してはMarkdownを用いることが有効だと思っています。そこで、筆者が自分なりにメリット・デメリットをまとめてみました。この記事も、Markdownによって記述されています。
メリット
- テキストなので軽い
- Git等でバージョン管理が行える
- 変更履歴を差分として残すことができる
- シーケンス図などが簡単にきれいに記述できる
- 見た目がきれい
- html, pdf, docxファイルなど他形式への変換が可能
- 環境に依存しない(Officeが無くても使える)
デメリット
- 表の作成がしにくい → エクセルで作成し読み込める
- 書き方を覚える必要がある → 一度覚えてしまえば効率的。比較的覚えやすい
- 作成結果をいちいち確認する必要がある → VScode,Atomを利用すれば書きながらプレビュー可能
エクセル、ワードとの比較
シーン | エクセル, ワードの仕様書 | マークダウン仕様書 |
---|---|---|
変更管理 | 変更管理ページを設け記載するため、変更記録に抜け漏れが発生する。わざわざ修正箇所を赤字にしている。 | バージョン管理ツールにログとして残るため明確 |
差分 | とれるツールもあるが使い勝手が悪い | Git diffで変更箇所が明確 |
修正点の指摘 | 指摘リストのエクセルなどを作り、担当が修正し、再度確認を行っている。 | GitHubを利用すればプルリクエストで第三者も容易に修正提案ができ、マージを終了した時点で修正が完了し、再度確認をする必要もない。 |
仕様書参照 | 技術的には可能(ハイパーリンク機能)だが運用されていないため、毎回文書を開き直し、該当箇所を探している | 相互にリンクを貼ることが当たり前になっていて、問題の箇所がすぐに見られる |
表作成 | エクセルが使いやすい | エクセルには勝てないが、エクセルの表から変換可能。cvsファイルも読み込み可能。 |
(*コチラのサイトを参考にさせてもらいました)
エディタ環境
筆者はVScodeを利用しています。
Markdownに関するプラグインは以下の6こを入れています。
- Markdown Preview Enhanced (必須)
- Markdown All in One (必須)
- Paste Image
- Markdown TOC
- Markdownlint
- Markdown PDF
詳しくはコチラを参照してください。 oratio.hatenablog.com
Markdownの書き方
見出し
<記述方法> # 見出し1 ## 見出し2 ### 見出し3 #### 見出し4 ##### 見出し5 ###### 見出し6
↓↓表示結果
リスト
<記述方法> - List-A - List-a - List-b - List-i 1. List-A 2. List-B 1. List-a 1. List-i
↓↓表示結果
文字装飾
装飾タイプ | 書き方 | Preview |
---|---|---|
太字 | **sample text** |
sample text |
下線 | <u>sample text</u> |
sample text |
取り消し | ~~sample text~~ |
|
色 | <font color="crimson">sample text</font> |
sample text |
サイズ | <span style="font-size: 200%"> sample text </span> |
sample text |
*フォントの色、サイズはmarkdownでは描けないのでhtmlを直接書きます。
改行
改行には、文末に半角スペースを2つ挿入します。
もしくはhtml記述方式で改行したい部分に\
を挿入します。
引用
> 引用
↓↓表示結果
"引用" 行を開けなければ複数行の引用が可能。
コード
コードの記述は「```」で記述したい範囲をはさみます。
例)cppコードの記述 ※「```」の後ろに記述タイプを記述することで設定されたハイライトで表示されます ```cpp // ここにコードを打ち込みます。 include <iostream> int main(void){ std::cout << "Hello world" << std::endl; return 0; } ```
↓↓表示結果
// ここにコードを打ち込みます。 include <iostream> int main(void){ std::cout << "Hello world" << std::endl; return 0; }
チェックボックス
- [ ] チェック1 - [x] チェック2
↓↓表示結果
表の作成
|要素1|要素2|要素3| |--|--|--| |hoge1|hoge2|hoge3| |foo1 |foo2 |foo3 |
要素1 | 要素2 | 要素3 |
---|---|---|
hoge1 | hoge2 | hoge3 |
foo1 | foo2 | foo3 |
ダイアグラムの記述方法
本記事ではMarkdownでダイアグラムを記述するためにmermaid (GitHub)を利用しています。エディタ環境がVScodeやAtomの方はmermaidを利用することが有効だと思います。 詳しい記述方法は公式サイトを参照してください。以下のサイトもわかりやすく載っています。
フローチャート
```mermaid graph LR A(Node A) -->|Link text| B(Node B) B --> C{Decision} C -->|One| D[Result one] C -->|Two| E[Result two] ```
シーケンス図
Markdoenでシーケンス図やフローチャート、ガントチャートなどを記述する場合、mermaid記述方式を利用します。
```mermaid sequenceDiagram Node_A->B:Node_AとBを実線 Node_A-->B:Node_AとBを点線 loop for n in foo[] Node_A-->B: foo loop! end alt is Ture B->>Node_A: start flag else is False B->>Node_A: end flag end opt something option Node_A-->B: get option end Node_A->>B:Node_AからBへ実線矢印 B-->>Node_A:BからNode_Aへ点線矢印 Node_A -x B:Node_AからBへ×付きの実線矢印 B --x Node_A:BからNode_Aへ×付きの点線矢印 B->>B:ループ Note right of B: This is comment Note over Node_A,B: Center comment ```
状態遷移図
例) ROSメッセージ通信の一つであるアクションの流れ
```mermaid stateDiagram state Action { Node_A --> Node_B Node_A --> Node_B : Results Node_A --> Node_C Node_C --> Node_B Node_B --> Node_A : Target value Node_C : Feed back state Node_A{ 送信バッファ } state Node_B{ 受信バッファ } } ```
円グラフ
```mermaid pie title Key elements in Product X "Data-A" : 42.96 "Data-B" : 50.05 "Data-C" : 10.01 "Data-D" : 5 ```
ガントチャート
```mermaid gantt title Project schedule section Item-A task_A :done, water_weapon, 2018-01-25 12:00:00, 2h task_B :active, fire_resistance_1, after water_weapon, 3h task_C :fire_resistance_2, after fire_resistance_1, 2h section Item-B task_A :thunder_weapon, after water_weapon, 3h task_B :poison_resistance, after fire_resistance_2, 3h task_C :down_resistance, after fire_resistance_2, 3h task_D :crit, after down_resistance, 2h ```
その他
csvファイルから表の作成
@import "testdata.csv"
↓↓表示結果