OpenNH

日常のひとこま(自分用のメモとかあれこれ)

Markdownで文書作成するメリットと書き方

目次


Markdownのメリット・デメリット


ワードやエクセルにもいいところがありますが、複数人で同じファイルを管理したり、仕様書などのようにバージョン管理されている文書に関してはMarkdownを用いることが有効だと思っています。そこで、筆者が自分なりにメリット・デメリットをまとめてみました。この記事も、Markdownによって記述されています。

メリット

  • テキストなので軽い
  • Git等でバージョン管理が行える
  • 変更履歴を差分として残すことができる
  • シーケンス図などが簡単にきれいに記述できる
  • 見た目がきれい
  • html, pdf, docxファイルなど他形式への変換が可能
  • 環境に依存しない(Officeが無くても使える)

デメリット

  • 表の作成がしにくい  → エクセルで作成し読み込める
  • 書き方を覚える必要がある → 一度覚えてしまえば効率的。比較的覚えやすい
  • 作成結果をいちいち確認する必要がある → VScode,Atomを利用すれば書きながらプレビュー可能

エクセル、ワードとの比較

シーン                                エクセル, ワードの仕様書 マークダウン仕様書
変更管理 変更管理ページを設け記載するため、変更記録に抜け漏れが発生する。わざわざ修正箇所を赤字にしている。 バージョン管理ツールにログとして残るため明確
差分        とれるツールもあるが使い勝手が悪い Git diffで変更箇所が明確
修正点の指摘        指摘リストのエクセルなどを作り、担当が修正し、再度確認を行っている。 GitHubを利用すればプルリクエストで第三者も容易に修正提案ができ、マージを終了した時点で修正が完了し、再度確認をする必要もない。
仕様書参照        技術的には可能(ハイパーリンク機能)だが運用されていないため、毎回文書を開き直し、該当箇所を探している 相互にリンクを貼ることが当たり前になっていて、問題の箇所がすぐに見られる
表作成        エクセルが使いやすい エクセルには勝てないが、エクセルの表から変換可能。cvsファイルも読み込み可能。

(*コチラのサイトを参考にさせてもらいました)



エディタ環境

筆者はVScodeを利用しています。

Markdownに関するプラグインは以下の6こを入れています。

詳しくはコチラを参照してください。 oratio.hatenablog.com



Markdownの書き方


見出し

<記述方法>
# 見出し1
## 見出し2
### 見出し3
#### 見出し4
##### 見出し5
###### 見出し6

↓↓表示結果

f:id:FounderLeis:20200212232819p:plain

リスト

<記述方法>
- List-A
  - List-a
  - List-b
    - List-i
1. List-A
2. List-B
   1. List-a
      1. List-i

↓↓表示結果

f:id:FounderLeis:20200213003354p:plain

文字装飾

装飾タイプ                          書き方 Preview
太字 **sample text** sample text
下線 <u>sample text</u> sample text
取り消し ~~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

↓↓表示結果

f:id:FounderLeis:20200213003919p:plain

表の作成

|要素1|要素2|要素3|
|--|--|--|
|hoge1|hoge2|hoge3|
|foo1 |foo2 |foo3 |
要素1 要素2 要素3
hoge1 hoge2 hoge3
foo1 foo2 foo3



ダイアグラムの記述方法


本記事ではMarkdownでダイアグラムを記述するためにmermaid (GitHub)を利用しています。エディタ環境がVScodeAtomの方は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]
    ```

f:id:FounderLeis:20200213001819p:plain

シーケンス図

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
    ```

f:id:FounderLeis:20200213001815p:plain

状態遷移図

例) 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{
                    受信バッファ
                }
            }
    ```

f:id:FounderLeis:20200213001813p:plain

円グラフ

    ```mermaid
    pie
        title Key elements in Product X
        "Data-A" : 42.96
        "Data-B" : 50.05
        "Data-C" : 10.01
        "Data-D" :  5
    ```

f:id:FounderLeis:20200213001811p:plain

ガントチャート

    ```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
    ```

f:id:FounderLeis:20200213001807p:plain



その他


csvファイルから表の作成

@import "testdata.csv"

↓↓表示結果

f:id:FounderLeis:20200212232823p:plain

ヘッダー・フッターの記述

word形式に出力

参考