Confluence で技術文書を開発する
Confluence は、技術文書の取り込み、配布、更新を支援する一連の機能やアドオンを備えた柔軟なプラットフォームです。以下に示すのは、技術文書サイトを始めるのに役立ち、文書のライフサイクルを管理する時間と労力を節約するヒントです。
ドキュメンテーション スペースを作成する
ドキュメントを開始するには
- Confluence のナビゲーションで、[スペース] > [すべてのスペースを表示] の順に選択します。[スペースの作成] をクリックします。
- 「ドキュメンテーション スペース」を選択して (これによって検索ボックス (livesearch マクロ) を備えたカスタム ホームページが提供され、最近の更新マクロ などを検索できます)、次へをクリックします。
- スペースに名前を付けて、作成 をクリックします。
Confluence はスペース キーを自動的に作成してスペース概要を作成します。概要はいつでも自由にカスタマイズしてください。ホームページの外観はお客様の思いどおりです!
コンテンツの再使用による時間の節約
単語、文、段落や画像、製品のバージョン番号、その他何でも、ドキュメンテーション スペースで何回も使用するつもりであれば、それを 1 回作成しておいて、あとで好きなだけページにインクルードできます（またはヘッダーやフッターに使用できます）。インクルードは、同じことを何度も入力する手間を省くだけでなく、変更がより簡単になります。47 か所で情報を更新するよりも、1 か所で更新する方がはるかに楽です。
コンテンツの再利用を可能にするマクロは 3 つあります：
- 抜粋マクロ： ページ上で再利用可能な部分を定義、または「抜粋」します － このマクロの中にコンテンツを追加すれば、好きなだけページで再利用できます。
- 抜粋インクルード マクロ (
excerpt-include) は別のページからの抜粋に含まれるコンテンツを含めます。 - ページ インクルード マクロ (
include) は、ページのコンテンツ全体を別のページに含めます。
例えば、製品のメジャーリリースごとにリリースノートを作成し、各リリースノートの前書きを「新着情報」ページにインクルードしたいと考えているとします。各リリースノートの前書きを抜粋マクロに入れ、次にリリースノートのセットごとの抜粋インクルードマクロを新着情報ページに追加します。前書きは魔法のように新着情報ページに表示され、リリースノートを更新すると、新着情報は自動的に更新されます。
- 抜粋: これらのページへの導入は、抜粋マクロにあります。
- 抜粋インクルード: 抜粋インクルード マクロです。
次は、インクルード ページ マクロのもう 1 つの使用例です。Atlassian のドキュメントに省略記号 (
) が表示されている場合 ( > [コピー] など)、この省略記号はインクルード ページ マクロによるものです。その画像しかないページがあるので、省略記号が必要になるたびにそのページを追加します。
小さな画像 1 つのためにインクルード ページ マクロを使用しているのはなぜでしょうか? UI 要素の変更に備えているためです。すべてのページに画像を添付した場合は、変更があったときに 50 ページの更新が必要になる可能性があります。インクルードページ マクロを使用していれば、1 度の更新ですべての箇所を変更できます。また、この方法によってその画像を使用しているページ数を把握できます。[] > [ページ情報] の順に移動すると、このページへのリンクの数と画像を使用しているページ数を確認できます。
インクルードライブラリーを作成する（オプション）
どの Confluence ページのコンテンツでもインクルードできますが、「インクルードライブラリー」を作成して、再利用専用にコンテンツを保存するのもよいでしょう。インクルードライブラリーは、Confluence の特殊な機能ではありません。インクルードライブラリーのページは、他の Confluence ページとまったく同じです。再利用専用にコンテンツを保存する場所が必要な場合に使える、単なるテクニックなのです。
インクルードライブラリーを作成するには：
をクリックし、スペースに新しいページを作成します。 - 適切なタイトルを入力します。ここでは「_ConfluenceInclusions」とします (タイトルの前のアンダースコアは、このページが特別であることを知らせるのに役立ちます)。
- コンテンツを入力し、ページを公開します。アトラシアンでは、インクルード ライブラリーの目的とコンテンツを再利用する方法を説明するテキストを入力しています。
- サイド バーで [スペース設定] を選択します。
- [ページを管理] カードから [並び替え] を選択します。
- 山括弧 [>] を選択して、ページ ツリーを展開します。
- スペース概要の上に新しいページをドラッグします。
- 新しいインクルード ページに移動して、 を選択し、再利用可能なコンテンツを含む子ページを追加します。
スペースの「ルート」にページを移動したため、スペース のページ セクションには表示されません。しかし、インクルードライブラリのページは普通の Confluence のページであるため、他の検索には表示されます。
- インクルージョン ライブラリの場所: インクルージョン ライブラリを、残りのドキュメントの上のこの場所にドラッグします。
ページ テンプレートを使用する
同じレイアウトで多くのページを作成している場合、1 つ以上のページテンプレートを作成しておくのは、実に時間の節約になります。あなたは常にパネルとコンテンツの表のように、同じマクロを追加する場合は、RSIから自分自身を保存し、テンプレートに入れて - あなたは1で始まり、しかし、あなたはあなたの効率を最大化するために必要な数を作ることができます。
すべてのスペースで利用可能なページ テンプレートを作成するには：
- 移動 Confluence のナビゲーション
(設定) - 左側の一覧からグローバル テンプレートおよびブループリントを選択します
- 右上にあるグローバル ページ テンプレートの追加ボタンを選択します。
- テンプレートページを作成し、保存を選択します。
ページテンプレートの詳細については、ブループリントおよびユーザーが作成したテンプレートを作成するを参照してください。
グローバル テンプレートおよびブループリントや、他の管理ページに素早く移動したい場合は、「/」を入力してから、参照したい管理ページの名前を入力します。
下書きを作成する
ドキュメントで新しいページを作成する際、時間をかけて、保存しながら作成し、数人にレビューをしてもらい、フィードバックを受け取りたいことでしょう。つまり、このワークフローは、「ドラフト、レビュー、公開」となります。
不完全なページはユーザーに見せたくないでしょうし、多くのドキュメントは最終版とする前にレビューが必要となります。そこで、ページのドラフト作成とレビューを可能にする技術をご紹介します。
- ページを作成し、権限を制限します。例えば、閲覧をチームなどの一連のユーザーに制限したり、特定のユーザーを指定したりできます。公開サイトの場合、閲覧をスタッフ メンバーのみに制限すれば、そのページは一般の人には表示されません。
- ページのコンテンツを記述します。
- レビュアーとページを共有し、フィードバックを依頼します (レビュアーにページへの閲覧制限をかけないようにご注意ください)。レビュアーはページの下部にコメントを追加したり、テキストを選択してインラインでコメントを追加したりできます。権限を付与すれば、レビュアーがページのコンテンツを直接編集することも可能です。
- 準備が整ったら、以下の手順にしたがってページを公開します。
- ページからコメントを削除する。
- ページ制限を解除し利用者が閲覧できるようにする。
これでページが公開されました。今度は、スペース権限とサイト権限により、ページを閲覧および／または更新できる人を決定します。
リンクとアンカーを使用する
リンクを追加する
いずれのドキュメンテーション サイトにおいても、ページからページへリンクを設定できる必要があり、ページの特定セクションへのリンクも珍しくありません。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 Diagram Connector では、Confluence Cloud サイトで図を作成し、挿入できます。フローチャート、ワイヤーフレーム、UML 図、マインド マップなどを機能豊富なエディタで簡単に作成できます。
テクニカル ドキュメントとしての Confluence をお試しください。
