あるまげどーーーん

某ITベンチャー会社に所属する技術者たちの自習室

BoostnoteとMarkdownでUML

きりんです。

Markdownでドキュメントを書きたい、できれば図表もテキストベースで書きたい、という事でMarkdownUMLの編集環境を模索してきました。 そんな中、最近知った「Boostnote」の使い勝手が良かったので、今まで試した環境と合わせてメモを残しておきたいと思います。

今まで試したもの

Atomエディタ + markdown-preview-enhanced

数年前に試したこの組み合わせ、プラグインのほかにPCにGraphvizのインストールも必要だったかもしれません。Atomエディタが重く感じられたので、だんだん使わなくなりました。

Nextclowd + Markdown Editorアプリ

サーバーにNextcloudをインストール、そこにMarkdown Editorアプリを追加することでブラウザ上でMarkdownUMLが書けるようになります。 Nextcloudは編集履歴が保存されるので簡単なバージョン管理もできます。難点としてはインストール先のレンタルサーバーが非力なせいかNextcloud自体の動きが時々怪しい事です。

Crowi + PlantUML

Crowiは会社のmajirou君が社内の情報共有のために用意してくれたサーバーで、Nextcloud同様ブラウザ上でMarkdownの編集を行います。別途用意したPlantUMLにUML図の画像を描画させそれをCrowi上(というかブラウザ上)に表示する、といった感じだったと思います。こちらもバージョン管理がされるので、どこを変更したか一目瞭然で使いやすいです。

Boostnote

Boostnote | Boost Happiness, Productivity, and Creativity.

上記環境や他のMarkdownエディタと比べた時のBoostnoteの(私にとっての)優位点は以下になります。

環境構築が簡単

やはりサーバーの設定などが必要になるとハードルがぐっと上がります。その点Boostnoteはダウンロードしてインストールすればすぐに使えるので導入がとても簡単です。

早い・軽い

Boostnoteと同様にローカルにインストールするAtomエディタと比較すると、起動も動作も早く軽く、最近よくフリーズする会社のPCでも快適に動作します。また、サーバーにインストールした環境と違いログイン不要ですぐに使えます。

UMLが書ける

UMLが書けるMarkdownエディタが少ない中、Boostnoteはmermaid.jsでもPlantUMLでもどちらの形式でもUMLが書けます。

イマイチなところ

一番下の行を編集中にその行が画面の外にはみ出してしまうことがあり、編集しづらくて困ることがあります。また、オンラインでの同期や編集履歴(バージョン管理)の機能はないので、別途自分で工夫する必要があります。いずれも致命的なデメリットではありませんが、ここが解消されるとさらに使い勝手がよくなると思います。

記述例

Markdown、PlantUMLの記述例です。

チェックリスト

f:id:nkhr22r:20181206235120p:plain

- [x] 予算申請
- [x] ハードウェア購入
- [ ] OSインストール
- [ ] 開発作業
- [ ] テスト
- [ ] 公開
シーケンス図

f:id:nkhr22r:20181206230816p:plain

@startuml
autonumber
skinparam {
  defaultFontName Migu 1P
  activityFontSize 14
}

actor ユーザー
participant Webアプリ
box "外部システム"
    participant WebAPI
    participant DB
end box

activate ユーザー
ユーザー->Webアプリ:リクエスト
activate Webアプリ
Webアプリ->WebAPI:リクエスト
activate WebAPI
WebAPI->DB:検索
activate DB
DB-->WebAPI:結果
deactivate DB
WebAPI-->Webアプリ:JSONデータ
deactivate WebAPI
Webアプリ-->ユーザー:HTMLデータ
deactivate Webアプリ
note over ユーザー:画面表示
deactivate ユーザー
@enduml
ガントチャート

f:id:nkhr22r:20181209215847p:plain

@startuml
project starts the 2018/11/19
saturday are closed
sunday are closed

[機能A実装] starts at 2018/11/19 and ends at 2018/11/23
[機能B実装] starts at 2018/11/22 and ends at 2018/11/28
[機能C実装] lasts 3 days
[機能A実装] -> [機能C実装]
[機能B実装] -> [機能C実装]
[統合テスト] happens at [機能C実装]'s end
@enduml
ワイヤーフレーム

f:id:nkhr22r:20181206234628p:plain

@startuml
salt
{+
ログイン
会員ID|"abc          "
パスワード|"********     "
[    送信    ]|[   リセット   ]
}
@enduml
その他

このほかにもPlantUMLではユースケース図やクラス図などの記述も可能です。詳しくは本家サイトをご参照ください。

Open-source tool that uses simple textual descriptions to draw UML diagrams.

業務での活用方法(模索中)

アイディアを練ってる段階や、下書きレベルではBoostnoteでサクサク文書を作成していきます。

作成した文書を社内で共有したい場合はBoostnoteからPDFで印刷してメール添付、記述形式に比較的互換性のあるCrowiに張り付け、あとは印刷して渡す、のどれかになるかと思います。

すでにやり取りがある業者ならPDFで渡しても問題ないと思いますが、お客様にはやはりOffice文書で渡す方が無難なので今は手動で転記しています。

今後の目標としてはRedmineUMLが使えるようにプラグインの導入を検討することと、編集データのオンラインストレージとの同期、バージョン管理方法の検討があげられます。


(2018.12.11追記) 公式のブログにMarkdown記法の記事がありました。ご参考まで。

仕事効率、学習効率を加速させるMarkdown記法の紹介 - Boostnote