この記事は Attlassian (JIRA, Confluence, Trello, Bitbucket) の Tips Advent Calendar 2017 の 23 日目の記事になります。
メディアマックスジャパン株式会社では JIRA, Confluence, Bitbucket をサーバー版で運用しています。今日は Confluence でエンジニア受けしやすいオススメアドオンを紹介しようと思います。
エンジニア受けしやすいってどういうこと？
Advent Calendar 経由で読んでいただいている方には当たり前だと思いますが Confluence はとても強力なドキュメント管理システムです。非エンジニアでもわかりやすい wysiwyg エディタや階層化機能、権限管理、多機能なマクロ、アドオンによる機能拡張など、プロジェクトで情報を共有する上で必要な機能は十分過ぎるぐらいに網羅されています。
Confluence 以前に利用していた Wiki 時代からは比べるのもおこがましいほど充実した情報共有環境を享受しています。
一方で、非エンジニアが使いやすい点は必ずしもエンジニアにとって使いやすいとは言えません。
老いも若きもエンジニアは GUI 嫌いが多く、自動化しやすい CUI とプレインテキスト、テキストエディタが大好きです。Qiita の Advent Calendar 2017 ランキングでは3位に Vim が入っているぐらいです。（なお、このランキングにはバグがあるようで、おそらく購読数 531 で1位であるはずの Visual Studio Code が入ってなかったり少々謎です）
そんなエンジニアにとってはテキストエディタで編集できることは非常に重要で、手元のエディタでメモを取る方がメインで、Confluence での共有は手元メモからの抜粋して転載するような形で使われがちです。
なので、エンジニアにとっては Confluence は転載先だと割り切って、この記事では弊社で採用しているエンジニアにとって標準とも言える Markdown と PlantUML フォーマットを利用できるアドオンを紹介したいと思います。
ちなみに私自身は IntelliJ, Visual Studio Code のススメという記事を書いているぐらいに GUI 好きです。個人用で使っているサービスも Workflowy をはじめとするクラウドツールに依存しているので今のメインエディタはブラウザだと断言できます。
Markdown プラグイン
Markdown はエンジニアにとって文書を書くための標準フォーマットになりました。
GitHub に Stack Overflow, Qiita などのエンジニア向けサイトの投稿フォーマットは Markdown 形式です。Atlassian スイートの中ではエンジニア向けツールである Bitbucket のコメントフォーマットも Markdown 形式が採用されています。
つまり Confluence を Markdown 対応させれば、エンジニアが普段から慣れている Markdown 形式のドキュメントをそのまま Confluence に貼り付けることができます。
Confluence の Markdown アドオンは多数ありますが、弊社では古くからありインストール数も 2.7K で一番多い Markdown Macro for Confluence というフリーのアドオンを利用しています。
使い方は上の画像のように非常に簡単で Markdown マクロを挿入して、そこに Markdown 形式のテキストを貼り付けるだけです。この例は CommonMark の sample から流用しました。
これでエンジニアが手元のテキストエディタで編集するメモをそのまま転載できる環境が整います。Confluence のマクロを使いたい場合は Markdown 部分を適当に分割して、その間に JIRA レポートなど Confluence マクロを埋め込めば、Confluence 機能を混在させることも問題なくできます。
ちなみに2017年12月現在だと Bitbucket や Github などの外部ソースからコンテンツを取り込める Markdown Extensions for Confluence というアドオンもあるので、他環境で Markdown を利用している場合はこちらを利用してみるのもいいかもしれません。
PlantUML for Confluence
Confluence でダイアグラムを書くために Gliffy Diagrams for Confluence を使っている人は多いと思います。UML や ERD, ネットワーク図をはじめ、サイトマップやワイヤフレーム、組織図やフロアプランにいたるまで、仕事で必要になるような図はなんでも描ける強力なダイラグラムエディタです。
弊社でも導入はしているのですがエンジニアからの受けはあんまり良くありません。ダイアグラムエディタはマウス操作が必須で Thinkpad を使っていないかぎりはキーボードから手を離して、タッチパッドであったりマウスを使ってレイアウトを調整したりする必要があるからではないかと思っています。
そこで導入したアドオンが PlantUML for Confluence です。PlantUML とはもともと UML を記載するテキストフォーマットですが、ガントチャートやワイヤフレームなど UML 以外の図も記述できるように拡張が続いています。
この PlantUML for Confluence 導入後、弊社エンジニアから感嘆の声を受けました。構造を記載すれば自動でレイアウトしてくれるし、テキストフォーマットなので Markdown 同様にエディタからのコピー＆ペーストが簡単にできます。
もちろんテキストエディタにも PlantUML を扱う拡張は各エディタに用意されていて、 VSCode など最近のエディタではリアルタイムにプレビューに反映させながら編集することが可能です。手元のエディタで図を完成させたら、あとは PlantUML マクロにテキストを貼り付けるだけです。
VSCode PlantUML 拡張の公式画像を引用しています。
エンジニアに楽をさせること
Atlassian 製品に限らずツールを導入するにあたってエンジニアに楽をさせることはとても重要です。
エンジニア以外の方は驚かれるかもしれませんが「怠惰」はプログラマの三大美徳の一つに挙げられています。エンジニアは怠惰であるからこそ楽をするために自動化や仕組みを作りだすことができるのです。
逆に言えば、エンジニアが使いなれたツールに歩みよって自動化できるような余地を与えることができればエンジニアをうまく巻き込むことができます。
今回紹介した Markdown や PlantUML などのエンジニアにとっての標準フォーマットに対応し HTTP API をはじめとする自動化可能な環境を用意してあげれば怠惰なエンジニアは楽をするためにお気に入りのエディタをカスタマイズして Confluence に自動投稿する仕組みを自ずと作りはじめるでしょう。
明日、クリスマスイブの Attlassian (JIRA, Confluence, Trello, Bitbucket) の Tips Advent Calendar 2017 は naru0504 さんの「CSSの基本をTrello CSS Guideから学ぶ」です。