linkマクロを使ってConfluenceのドキュメントクオリティを上げる話
こんにちは、みみぞうです。
ナビタイムジャパンで『システムや開発環境、チームの改善』を担当しています。
本記事では、Confluenceのlinkマクロを使ってドキュメントクオリティを上げる方法を紹介します。
読んで欲しい方
以下のような方を対象としています。
❶ Confluenceを使っている
❷ 同じような名前のページが散乱しておりどれを見ていいか困っている
同じ情報があちこちにある問題
ナビタイムジャパンではConfluenceでドキュメント管理をしています。Confluenceでは異なるスペースで同じ名前のページを作成できるため、知らないうちに同じ名前のページばかりになってしまうことがあります。
たとえば、『乗換NAVITIME』に関する情報を調べようとした場合は以下のようになります。どれが信用できるのでしょうか...
『最新情報がメンテナンスされた唯一のページがサジェストされたら..』と思うことでしょう。この問題を少しでも減らすためlinkマクロを使ってみます。
Confluenceのlinkマクロ
linkマクロは既存ページへのリンクを挿入できる機能です。
リンクの方法としては他にもハイパーリンクがあります。しかし、linkマクロは以下の点でハイパーリンクより優れています。
❶ 既存のページから検索できる
❷ リンク先ページが変更/削除されても更新される
❸ ページを参照しているページ一覧が分かる
次のセクションで詳しく説明します。
既存のページから検索できる
キーワードを挿入すると既存のページ一覧が候補として表示されます。
これから入力しようとした用語を直接入力ではなく、linkマクロを使って挿入してみましょう。既に同様のページがある場合は無駄なページを増やさずに済みます。更に信頼できるページへのリンクもできて一石二鳥です。
また、定義されていると思っていた用語を入力しても候補に表示されない場合は『その用語が曖昧な使われ方をされているかもしれない』シグナルです。用語のページを作成し、関係者で認識を合わせましょう😉
リンク先ページが変更/削除されても更新される
ドキュメントは時間と共に変化します。用語の名前が変わったり、用語がなくなることもあります。都度リンク先の状況をすべて把握するのは現実的ではありません。
linkマクロはリンク先ページが更新/削除された場合も上手く反映してくれます。具体例として、以下のページで『素晴らしい機能(ストック型)』というページへのlinkマクロを挿入したケースを考えます。
『素晴らしい機能(ストック型)』ページはしばらくして削除されてしまいました。その場合、表示は以下のようになります。元のページ名および削除されたことが分かりますね😄
また、ページ名が変更された場合も自動で反映されます。『素晴らしい機能(ストック型)』ページを『かなりいい機能(ストック型)』という名前に変えてみました。すると以下のようになります。
そのため、『ページ名を変更する場合はページの意味が変わらないようにする』ことをオススメします。
たとえば『素晴らしい機能(ストック型)』のページを全く関係ない『日報』という名前に変更し、中身もすべて書き換えてしまったとします。その場合、『素晴らしい機能(ストック型)』を参照していたページは以下のようになってしまいます。
これでは意味が通じなくなってしまいます。一度作成したページは意味が変わらないように運用し、別の意味を持つページは新しく作りましょう。
ページを参照しているページ一覧が分かる
ここまでlinkマクロの有用性をお伝えしましたが、関連しているがゆえに『ページを編集したときの影響が怖い』と感じることもあるでしょう。実はとても大切なページで使われていることも知らず、削除してしまった..とか。
linkマクロでリンク先ページと連携した場合、リンク先ページで『どのページから参照されているか』をページ右上メニューから確認できます。
↓
ページを変更する前に影響範囲が分かるので安心ですね😄 ページ削除のように重要なアクションの場合は確認ダイアログでも教えてくれます。
まとめ
Confluenceのlinkマクロを使ってドキュメントクオリティを上げる方法を紹介しました。
他にもlinkマクロには『ドキュメンテーションツールの移行がしやすい』というメリットがあります。先日ナビタイムジャパンではConfluenceのクラウド移行を完了させましたが、linkマクロを使っているページはリンク切れの心配もなく移行がスムーズでした。
Jira/Bitbucketも含めたAtlassian製品のクラウド移行は以下のイベントでも発表しております。興味ある方いらっしゃいましたらご覧いただければと思います。