Confluence で技術文書を開発する

Confluence は、技術ドキュメントの管理、配布、更新を支援する一連の機能や Marketplace アプリを備えた柔軟なプラットフォームです。自身の技術ドキュメント サイトを開始し、ドキュメントのライフ サイクルを管理するための時間や労力を削減するためのヒントについて、以降で説明します。

Confluence をドキュメント作成に使用する方法について説明した別の概要資料として、アトラシアンのソリューション パートナーである K15t の｢Rock the Docs｣をご覧ください。 

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

Confluence にスペースを作成するのは、迅速かつ簡単です。ドキュメンテーション スペースを始めるのに必要なのは、Confluence のヘッダからスペース > スペースの作成 を選択することだけです。さらに簡単に実行するには、スペース作成ダイアログで「ドキュメンテーション スペース」オプションを選択します。これによって検索ボックス（ライブサーチマクロ）を備えたカスタムホームページが提供され、ドキュメンテーション スペースや最近更新されたマクロ、その他のグッズを検索できます。

スペースに名前を付けると、Confluence は自動的にホームページとスペースキーを作成します（ Confluence が選択したスペースキーに満足できない場合は、スペースキーを変更します）。ホームページはいつでも自由にカスタマイズしてください。ホームページの体裁はまったく自分の思いどおりにできます！

---

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

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

On this page:

関連ページ

• スペース

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

• 抜粋マクロページ上で再利用可能な部分を定義、または「抜粋」します。このマクロの中にコンテンツを追加すれば、好きなだけページで再利用できます。
• 抜粋インクルード マクロ (excerpt-include) は別のページから抜粋したコンテンツを含めます。
• ページ インクルード マクロ (include) は、ページのコンテンツ全体を別のページに含めます。

たとえば、製品のメジャーリリースごとにリリースノートを作成し、各リリースノートの前書きページを '新着情報' ページに含めます。各リリースノートの前書きを抜粋マクロに配置し、次に リリースノートのセットごとの抜粋を含めるマクロを新着情報ページに追加します。前書きは魔法のように新着情報ページに表示され、リリースノートを更新すると、新着情報は自動的に更新されます。

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

インクルード ページ マクロのもう 1 つの使用例を紹介します。省略記号 (

) がドキュメントに表示される場合、たとえば  > [コピー] に移動します、という手順が表示されている場合、実際はこの省略記号はインクルード ページ マクロです。その画像のみを含むページがあるので、省略記号が必要になるたびに、そのページを含めることができます。

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

 ) > [ページ情報] に移動すると、このページに対するリンクの数と画像を使用しているページ数を確認できます。

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

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

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

1. 作成を選択し、スペースに新しいページを作成します
2. 適切なタイトルを入力します。ここでは「_ConfluenceInclusions 」を使用します（タイトルの前のアンダースコアは、このページが特別であることを知らせるのに役立ちます）
3. コンテンツを入力し、ページを保存します
   私たちの場合、インクルードライブラリーの目的とコンテンツを再利用する方法を説明するテキストを入力しています
4. スペース ツール > ページ順序の変更を選択し、新しいページをスペース ホームページの上にドラッグします。
5. 新しいインクルードページに移動して、作成を選択し、再利用可能なコンテンツを含む子ページを追加します

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

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

---

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

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

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

1. 移動 

   Error rendering macro 'includeplus'

   User 'anonymous' does not have permission to view the page with ID 1255454939.

2. 左側の一覧からグローバル テンプレートおよびブループリントを選択します
3. 右上にあるグローバル ページ テンプレートの追加ボタンを選択します。
4. テンプレートページを作成し、保存を選択します。

ページ テンプレートの詳細については、テンプレートを作成する を参照してください。

---

下書きを作成する

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

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

1. ページを作成し、権限を制限します。
   例えば、閲覧をチームのピープルに制限したり、数人のメンバーに限定したりできます。パブリックサイトでは、閲覧をスタッフメンバーにのみ制限すれば、一般の人々はページを見ることができません。
2. ページのコンテンツを記述します。
3. レビュアーとページを共有し、フィードバックを依頼します（レビュアーにページへの閲覧制限をかけないように注意してください）。
   レビュアーはページの下部にコメントを追加したり、テキストをハイライト表示してインラインでコメントを追加したりできます。権限を付与すれば、レビュアーがページコンテンツを直接編集することも可能です。
4. 準備が整ったら、以下の手順にしたがってページを公開します。
   1. ページからコメントを削除する。
   2. ページ制限を解除し利用者が閲覧できるようにする。

これでページが公開されました。今度は、スペース権限とサイト権限により、ページを閲覧および／または更新できる人を決定します。

---

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

リンクを追加する

いずれのドキュメンテーション サイトにおいても、ページからページへリンクを設定できる必要があり、ページの特定セクションへのリンクも珍しくありません。Confluence ページにはどんな URL でも追加可能です。Confluence が自動的に検知し、リンクへと変換します。

Confluence サイトの他のページに URL を貼った場合、Confluence はリンクテキストをページ名として表示し、関連リンクに変換します。つまり、もし、ページ名が変更されても、Confluence がリンクを調整するためリンクが切れることはありません。

アンカーの追加とリンク

アンカーマクロを使用すると、他のページからリンクさせることができるアンカーをドキュメントに作成できます。ページのトップにアンカーを追加してあるので、トップへ戻るをクリックすると、ページのトップに戻ります。

同じページ内でリンクするマクロを追加するには：

1. エディタに「{anchor」と入力し、アンカー マクロを選択して、アンカーに名前 (例: top) を付けます。
2. マクロにリンクするテキストを選択し、Ctrl+K (Windows) または Cmd+K (Mac) と入力します (リンク ダイアログが開きます)。
3. 左側のオプションから [詳細] を選択し、「#」と入力してからアンカー名を続けます (例: #top)。

他ページのアンカーへリンクさせる際の概要全般とアンカーの利点については、リンクと アンカーに関するドキュメントを参照してください。

---

便利なマクロ

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

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

コンテンツ テーブル マクロは、コンテンツの内容を要約し、ページで使用されているヘッダーへのリンクを提供することで、長いページをナビゲートします。最も優れているのは、マクロを追加するだけでよいという点です。一旦マクロを追加すれば、マクロが自動的にヘッダーを検知し、コンテンツテーブルに追加してくれます。

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

ドキュメントを作成していると、よく、強調したい要素や読者の注意を惹き付けたい要素が出てきます。Confluence は、ヒント・情報・警告・注意・パネルマクロを備えています。コンテンツの特定の部分に読者の注意を惹き付けたい時に大変便利です。

---

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

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

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

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

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

ページ履歴を見る

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

ページ履歴を表示するには、該当のページに移動して、 

 > [ページ履歴] を選択します。

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

• ページの特定のバージョンのコンテンツを見る。
• 指定のバージョンに戻す（復元する）。
• 2 バージョン選択して比較し、変更箇所を確認する。

詳細な説明については、ページ履歴およびページ比較ビューを参照してください。

投稿者リストを表示する

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

---

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

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

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

---

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

Confluence は技術ドキュメントのために必要な機能をひととおり備えていたツールですが、ドキュメントやワークフローのニーズに合わせて機能を追加することもできます。Atlassian Marketplace に、Confluence の機能を拡張できる便利なアプリが用意されています。これらの多くはアトラシアンでも使用しています。

Marketplace には常に新しいアプリが追加されています。最新の情報については Marketplace をご参照ください。

Scroll Versions (ベンダーによるサポート)

Scroll Versions（K15t 社製）を使用すれば、ドキュメントバージョンと製品バージョンを連携させることができます。これにより、製品の新バージョンが出たら、そのバージョンのドキュメントを公開されるように設定できます。ドキュメントのバージョンを好きなだけ作成し、必要な変更を加え、リリース時まで公開せずに保存しておきます。複数の異なるドキュメント（例えば、異なる OS 向けの複数バージョンのドキュメント）を複数のスペースや Confluence インスタンスに対し公開することも可能です。

Copy Space（サポート対象外）

アトラシアンラボ作成の Copy Space アドオンは、その名のとおり、これを使用すれば、スペース管理者は、スペース内のページを含めてスペースをコピーできます。スペースを新たに作成するためにコピーして使用できるスペーステンプレートが必要な場合に大変便利です。

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

 現時点で、このプラグインではページ履歴、ブログ投稿、メールをコピーできません。

Scroll PDF Exporter (ベンダーによるサポート)

ドキュメンテーション スペースで PDF を作成するなら、本格的なフォーマットを使用したくありませんか？Scroll PDF Exporter（K 15 社製）なら、便利な PDF テンプレートを使用して、1 ページだけでもスペース全体でもエクスポート用にスタイル設定ができます。

Gliffy (ベンダーによるサポート)

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

Lucidchart (ベンダーによるサポート)

Lucidchart はクラウド版とサーバー版で利用可能です。Lucidchart は、Confluence Cloud 環境で図を作成し、挿入することができます。フローチャート、ワイヤーフレーム、 UML 図、マインドマップなどを機能豊富なエディタで簡単に作成できます。

サーバー版では無料の Visio ビュアーも備わっているため、Microsoft Visio (.vsd) ファイルや Visio stencils (.vss) を見ることができます。また、Visio へのエクスポートもサポートされています。

ドキュメント用テーマ (中止された機能)

Confluence はこれまで特にドキュメント用にテーマを提供してきました。このテーマは Confluence 6.0 では削除されました。

ヘッダーやフッター、およびサイドバーへのカスタム コンテンツの追加機能など、オリジナルのドキュメント用テーマ機能の多くが、Confluence のモダンな既定テーマで利用できるようになりました。ドキュメントのスペースでぜひご利用ください。