Confluence を技術文書の作成に使用する

Confluence は、技術文書の取り込み、配布、更新を支援する一連の機能やアドオンを備えた柔軟なプラットフォームです。独自の技術文書スペースを開き、ドキュメントのライフサイクルを管理する時間や労力を節約するためのヒントについて、以降で説明します。

ドキュメンテーション スペースを作成する

ドキュメントを開始するには

1. Confluence のナビゲーションで、[スペース] > [すべてのスペースを表示] > [スペースを作成] の順に選択します。

2. [文書のスペース] を選択して (これによって検索ボックス (livesearch マクロ) を備えたカスタム ホームページが提供されて、最近の更新マクロなどを検索できます) [次へ] をクリックします。

3. スペースに名前を付けて、作成 をクリックします。

Confluence はスペース キーを自動的に作成してスペース概要を作成します。概要はいつでも自由にカスタマイズしてください。ホームページの外観はお客様の思いどおりです!

コンテンツの再使用による時間の節約

単語、文、段落や画像、製品のバージョン番号、その他何でも、ドキュメント スペースで何回も使用するつもりであれば、それを 1 回作成しておいて、あとで好きなだけページに含める (インクルードする)、またはヘッダーやフッターに使用できます。インクルードは、同じことを何度も入力する手間を省くだけでなく、変更がより簡単になります。47 か所で情報を更新するよりも、1 か所で更新する方がはるかに楽です。

コンテンツの再利用を可能にするマクロは 3 つあります。

• 抜粋マクロ: ページ上で再利用可能な部分を定義または「抜粋」します。このマクロの中にコンテンツを追加すれば、好きなだけページで再利用できます。

• 抜粋インクルード マクロ (excerpt-include) は別のページからの抜粋に含まれるコンテンツを含めます。

• ページ インクルード マクロ (include) は、ページのコンテンツ全体を別のページに含めます。

たとえば、製品のメジャー リリースごとにリリース ノートを作成して、各リリース ノートの前書きページを「新着情報」ページに含めるとします。各リリース ノートの前書きを抜粋マクロに、次に一連のリリース ノートの抜粋インクルード マクロを新着情報ページに追加します。前書きがさっと新着情報ページに表示されて、リリース ノートを更新すると新着情報も自動で更新されます。

1. 抜粋: これらのページへの導入は、抜粋マクロにあります。 

2. 抜粋インクルード: 抜粋インクルード マクロです。 

インクルード ページ マクロのもう 1 つの使用例を紹介します。アトラシアンのドキュメントに省略記号が表示されている場合 ([] > [コピー] など)、この省略記号はインクルード ページ マクロによるものです。その画像しかないページがあるので、省略記号が必要になるたびにそのページを追加します。

小さな画像 1 つのためにインクルード ページ マクロを使用しているのは、UI 要素の変更に備えているためです。すべてのページに画像を添付した場合は、変更時に 50 ページの更新が必要になる可能性があります。インクルード ページ マクロを使用していれば、1 度の更新ですべての箇所を変更できます。また、この方法によってその画像を使用しているページ数を把握できます。[] > [ページ情報] の順に移動すると、このページに対するリンクの数と画像を使用しているページ数を確認できます。

インクルードライブラリーを作成する（オプション）

どの Confluence ページのコンテンツでもインクルードできますが、「インクルードライブラリー」を作成して、再利用専用にコンテンツを保存するのもよいでしょう。インクルードライブラリーは、Confluence の特殊な機能ではありません。インクルードライブラリーのページは、他の Confluence ページとまったく同じです。再利用専用にコンテンツを保存する場所が必要な場合に使える、単なるテクニックなのです。

インクルードライブラリーを作成するには：

1. [作成] を選択して、スペースに新しいページを作成します。 

2. 適切なタイトルを入力します。ここでは「_ConfluenceInclusions」とします (タイトルの前のアンダースコアは、このページが特別であることを知らせるのに役立ちます)。 

3. コンテンツを入力し、ページを公開します。アトラシアンでは、インクルード ライブラリーの目的とコンテンツを再利用する方法を説明するテキストを入力しています。 

4. サイド バーで [スペース設定] を選択します。

5. [ページを管理] カードから [並び替え] を選択します。 

6. 山括弧 [>] を選択して、ページ ツリーを展開します。

7. スペース概要の上に新しいページをドラッグします。 

8. 新しいインクルード ページに移動して [作成] を選択し、再利用可能なコンテンツを含む子ページを追加します。

9. インクルージョン ライブラリの場所: インクルージョン ライブラリを、残りのドキュメントの上にドラッグします。 

スペースの「ルート」にページを移動したため、スペース のページ セクションには表示されません。しかし、インクルードライブラリのページは普通の Confluence のページであるため、他の検索には表示されます。

ページ テンプレートを使用する

同じレイアウトで多くのページを作成している場合、1 つ以上のページテンプレートを作成しておくのは、実に時間の節約になります。あなたは常にパネルとコンテンツの表のように、同じマクロを追加する場合は、RSIから自分自身を保存し、テンプレートに入れて - あなたは1で始まり、しかし、あなたはあなたの効率を最大化するために必要な数を作ることができます。

すべてのスペースで利用可能なページ テンプレートを作成するには：

1. 右上隅の歯車アイコン () を選択して Confluence 管理を開きます。

2. 左側のナビゲーションで「設定」>「設定」を探します。

3. 「グローバル テンプレートとブループリント」を選択します。

4. 右上にある「グローバル ページ テンプレートを追加」ボタンを選択します。

5. テンプレート・ページを作成し、「保存」を選択します。

ページ テンプレートの詳細については「ブループリントとユーザーが作成したテンプレート」をご参照ください。

「グローバル テンプレートとブループリント」や他の管理ページにすばやく移動するには、/ キーを押して、探している管理ページの名前を入力し始めます。

下書きを作成する

ドキュメントで新しいページを作成する際、時間をかけて、保存しながら作成し、数人にレビューをしてもらい、フィードバックを受け取りたいことでしょう。つまり、このワークフローは、「ドラフト、レビュー、公開」となります。

不完全なページはユーザーに見せたくないでしょうし、多くのドキュメントは最終版とする前にレビューが必要となります。そこで、ページのドラフト作成とレビューを可能にする技術をご紹介します。

1. ページを作成し、その権限を制限します。たとえば、閲覧をチームなどのユーザー・グループに制限したり、特定のユーザーを指定したりできます。公開インスタンスの場合、閲覧をスタッフ・メンバーのみに制限すれば、そのページは一般の人には表示されません。

2. ページのコンテンツを記述します。 

3. レビュアーとページを共有して、フィードバックを依頼します (レビュアーにページへの閲覧制限をかけないようにご注意ください)。レビュアーは、ページの下部にコメントを追加、テキストを選択してインラインでコメントを追加できます。また、権限を付与すれば、レビュアーはページのコンテンツを直接編集できます。

4. 準備が整ったら、以下の手順にしたがってページを公開します。

   1. ページからコメントを削除する。 

   2. ページ制限を解除し利用者が閲覧できるようにする。 

これでページが公開されました。今後、ページの閲覧や更新が可能なユーザーは、スペース権限とサイト権限によって決まります。

リンクとアンカーを使用する

リンクを追加する

どのようなドキュメンテーション・スペースでも、あるページから別のページへ、さらにはページ上の特定のセクションへリンクできるようにすることが不可欠です。Confluence ページには任意の URL を追加でき、Confluence はそれを自動的に検知し、リンクに変換します。

Confluence インスタンスに別のページの URL を貼り付けると、Confluence はリンク・テキストをページ名として表示し、相対リンクに変換します。つまり、ページ名が変更された場合、Confluence はリンク切れにならないように、そのリンクを調整します。

アンカーの追加とリンク

レガシー エディターでは、アンカー マクロによって任意の場所からリンクできるアンカーをドキュメントに作成できます。このページではトップにアンカーを追加してあるので、それをクリックするとページのトップに戻ります。このマクロは、新しいエディターでは利用できません。

レガシーまたは新しい各エディターでコンテンツをリンクする方法の詳細については、リンクとアンカーのドキュメントをご確認ください。

便利なマクロ

Confluence ではさまざまなマクロを用意しています。技術文書に非常に便利なマクロも数種類ありますので、いくつかご紹介します。

コンテンツ テーブル マクロ

目次マクロではコンテンツの構成を要約してページで使用されている見出しへのリンクを提供できるため、長いページのナビゲーションに役立ちます。マクロを追加するだけで使用できるのが最大の長所です。一度マクロを追加するとマクロが見出しを自動で検出して、それらを目次に追加します。

ヒント・注意・情報・警告・パネルマクロ

ドキュメントの作成時には、よく強調したい要素や読者の注意を惹き付けたい要素が出てくるものです。Confluence では、ヒント、情報、警告、注意、パネルの各マクロが用意されています。これらは、コンテンツの特定の部分に読者の注意を惹き付ける際に効果抜群です。

これらのマクロはそれぞれ従来のエディタの一部ですが、新しいエディタでは 1 つの情報パネル要素にまとめられています。

ページ更新をトラッキングする

Confluence では、1 ページを複数の人間が更新することがよくあります。テクニカルライターは、レビュー中も公開後も、ドキュメントの状態を把握しておく必要があります。

ページやスペースをウォッチする

変更があった際にわかるように、ページやスペース全体すらもウォッチすることをお勧めします。ウォッチしているページに変更やコメントが加えられると、誰がどのような変更を行ったかについてメール通知されます。

ドキュメンテーション スペースのページを開いているときに、右上にあるウォッチボタンを選択します。そのページのみをウォッチするか、スペースの全ページをウォッチするか選択できます。

ページ履歴を見る

Confluence は、ページが編集される度に新しいバージョンを作成します。ページ履歴は、更新日、作成者、コメントとともにすべてのバージョンを表示します。

ページ履歴を確認するには、該当のページに移動して [ページ履歴] を選択します。 

ページ履歴ビューでは、以下の操作が可能です。

• ページの特定のバージョンのコンテンツを見る。

• 指定のバージョンに戻す (復元する)。

• 2 バージョン選択して比較し、変更箇所を確認する。

投稿者リストを表示する

ページの更新者を知りたい場合は、投稿者マクロを追加できます。このマクロは、作成、編集を行った投稿者のリスト (カスタマイズ可能) を表示します。オプションで、コメントした投稿者も表示できます。

PDF エクスポートのカスタマイズ

ドキュメントを PDF で提供する予定がある場合は (メール、ダウンロード、印刷、その他の配信方法により)、タイトルページ、ヘッダー、フッターを追加することで PDF の表示をカスタマイズできます。

実行するプロセスは、PDF エクスポートのカスタマイズを 1 つのスペースに対して行うか、インスタンス全体に対して行うかによって異なります。このような変更を実行したい場合は、「PDF へのエクスポートをカスタマイズする」ページで詳細な方法をご確認ください。

その他の便利なツールとアプリ

ドキュメントやワークフローのニーズに合わせてアプリを使用して、Confluence を拡張できます。Confluence の機能を拡張できる便利なアドオンが、Atlassian Marketplace で提供されています。これらの多くはアトラシアンでも使用しています。

Copy Space (サポート対象外)

Copy Space for Confluence アプリによって、その名のとおり、スペース管理者はスペース内のページを含むスペース全体をコピーできます。他のスペースを作成する際にコピーして使用するスペース テンプレートがある場合に、大変便利です。

このアプリは、現在のスペースを特定のタイミングでアーカイブする必要がある場合にも便利です。例えば、製品のとあるバージョンから次のバージョンへ移行する際などに、スペースをコピーし、新しい名前を付け、任意の場所に保存しておけば、既存のスペースを失うことはありません。

 Copy Space アプリでは現在、ページ履歴、ブログ投稿およびメールのコピーは行われません。

Gliffy（サポート対象）

Gliffy によって、図、ワイヤーフレーム、フローチャートなどを作成できます。Gliffy の特長は、極めて直観的なドラッグ & ドロップのインターフェイスです。また、JPEG、PNG、SVG などの様々なフォーマットに図をエクスポートできます。Gliffy のフローチャート、 UI ワイヤーフレーム、ネットワーク図を Confluence ページに直接追加して、アイデアを視覚的に伝えて理解し、チーム全体で素早く共有しましょう。

Lucidchart（サポート対象）

Lucidchart Diagrams Connector を使用すると、Confluence Cloud インスタンス内で図を作成して挿入できます。機能豊富なエディターで、フローチャート、ワイヤーフレーム、UML 図、マインド・マップなどを簡単に作成できます。

テクニカル ドキュメントとしての Confluence をお試しください。