Confluence で技術文書を開発する

スペースのテーマを「ドキュメンテーション」に設定したい場合、サイドバーの下部からスペースツール > ルックアンドフィールを選択したあと、テーマを選択し、ドキュメンテーション テーマを選択します。

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

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

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

• 抜粋マクロ：ページ上で再利用可能な部分を定義、または「抜粋」します－ このマクロの中にコンテンツを追加すれば、好きなだけページで再利用できます。
• The Excerpt Include macro (excerpt-include) to include the contents of an excerpt on another page.
• The Include Page macro (include) to include the entire content of a page on another page.

例えば、製品のメジャーリリースごとにリリースノートを作成し、各リリースノートの前書きを「新着情報」ページにインクルードしたいと考えているとします。各リリースノートの前書きを抜粋マクロに入れ、次にリリースノートのセットごとの抜粋インクルードマクロを新着情報ページに追加します。前書きは魔法のように新着情報ページに表示され、リリースノートを更新すると、新着情報は自動的に更新されます。

Another example is one of the ways we use the Include Page macro. Whenever the ellipsis () appears in our documentation – for example, go to  > Copy – it's actually an Include Page macro. We have a page with just that image on it, so we can include it whenever we need an ellipsis.

Why do we do use an Include Page macro for one tiny image? Well, just in case that UI element is ever changed. If we attach the image to every page, there might be 50 pages we need to update when things change; if we use an Include Page macro, we update once and it's changed everywhere. Doing it this way also allows us to know how many pages we're using the image on. By going to  > Page Information, we can see how many incoming links there are to this page, and that tells us how many pages use the image.

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

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

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

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

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

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

同じレイアウトで多くのページを作成している場合、1 つ以上のページテンプレートを作成しておくのは、実に時間の節約になります。パネルやコンテンツの表のように、常に同じマクロを追加している場合、それをテンプレートに入れて、反復操作のストレスから自分を守りましょう － テンプレート作成は 1 つから始められ、必要な数だけ作って効率を最大化できます。

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

1. 移動 

    > General Configuration

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

To view page history, go to the page and choose  > Page History

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

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

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

投稿者リストを表示する

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

PDF エクスポートをカスタマイズする

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

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

その他の便利なツールとアドオン

Confluence is already a great tool for technical documentation, but you can still add to it depending on your documentation and workflow needs. Here are some useful add-ons available on the Atlassian Marketplace, most of which we use ourselves, which can extend the functionality of Confluence.

Scroll Versions（サポート対象）

Scroll Versions, by K15t, allows you to tie versions of your documentation to versions of your product, so that when a new version of your product ships you can publish that version of your documentation. Create as many versions of your documentation as you like, make the changes you need to, and keep them up your sleeve until release time. You can even publish different variations of your documentation – like if you have versions of your documentation for different operating systems – to different spaces or Confluence instances.

Copy Space（サポート対象外）

The Copy Space add-on does what its name suggests; it allows a space administrator to copy a space, including the pages within the space. Great for when you want a space template that you can copy to create other spaces.

このプラグインは、現在のスペースをゆくゆくはある時点でアーカイブする必要が出てきたときにも大変便利です。例えば、製品のとあるバージョンから次のバージョンへ移行する際など、スペースをコピーし、新しい名前を付け、好きなところに保存しておけば、既存のスペースを失うこともありません。

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

Scroll PDF Exporter（サポート対象）

If you're going to produce a PDF of your documentation space, wouldn't you like it to be professionally formatted? The Scroll PDF Exporter, by K15t, lets you style single pages or whole spaces for export, using handy PDF templates.

Gliffy（サポート対象）

Create diagrams, wireframes, flowcharts and more with Gliffy. Gliffy features a highly intuitive drag-and-drop interface, and allows you to export your diagrams in multiple formats, including: JPEG, PNG and SVG. Add Gliffy flowcharts, UI wireframes, and network diagrams directly to your Confluence pages to communicate your ideas visually, making them easy to understand and faster to spread through your team.

Lucidchart（サポート対象）

Lucidchart is available in versions for Cloud and Server, and allows you to create and insert diagrams within your Confluence Cloud environment. Quickly draw flowcharts, wireframes, UML diagrams, mind maps, and more inside our feature-rich editor.

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