コンテンツの再利用を可能にするマクロは 3 つあります：
- The Excerpt macro to define a re-usable section, or 'excerpt', on a page – add content inside this macro, and you can reuse it on as many pages as you like.
- 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.
たとえば、製品のメジャーリリースごとにリリースノートを作成し、各リリースノートの前書きページを '新着情報' ページに含めます。各リリースノートの前書きを抜粋マクロに配置し、次に リリースノートのセットごとの抜粋を含めるマクロを新着情報ページに追加します。前書きは魔法のように新着情報ページに表示され、リリースノートを更新すると、新着情報は自動的に更新されます。
- 抜粋: これらのページへの導入は、抜粋マクロにあります。
- 抜粋インクルード: 抜粋インクルード マクロです。
インクルード ページ マクロのもう 1 つの使用例を紹介します。省略記号 (
小さな画像 1 つのためにインクルード ページ マクロを使用しているのは、UI 要素の変更に備えているためです。すべてのページに画像を添付した場合は、変更があったときに 50 ページの更新が必要になる可能性があります。インクルードページ マクロを使用していれば、1 回の更新ですべての箇所を変更できます。また、この方法によってその画像を使用しているページ数を把握できます。(
インクルードライブラリーを作成する（オプション）
どの Confluence ページのコンテンツでもインクルードできますが、「インクルードライブラリー」を作成して、再利用専用にコンテンツを保存するのもよいでしょう。インクルードライブラリーは、Confluence の特殊な機能ではありません。インクルードライブラリーのページは、他の Confluence ページとまったく同じです。再利用専用にコンテンツを保存する場所が必要な場合に使える、単なるテクニックなのです。
インクルードライブラリーを作成するには：
- 作成を選択し、スペースに新しいページを作成します
- 適切なタイトルを入力します。ここでは「_ConfluenceInclusions 」を使用します（タイトルの前のアンダースコアは、このページが特別であることを知らせるのに役立ちます）
- コンテンツを入力し、ページを保存します
私たちの場合、インクルードライブラリーの目的とコンテンツを再利用する方法を説明するテキストを入力しています - スペース ツール > ページ順序の変更を選択し、新しいページをスペース ホームページの上にドラッグします。
- 新しいインクルードページに移動して、作成を選択し、再利用可能なコンテンツを含む子ページを追加します
スペースのルートにページを移動したため、 サイドバーのページツリーには表示されません。しかし、インクルードライブラリのページは普通の Confluence のページであるため、他の検索には表示されます。
- インクルージョン ライブラリの場所: インクルージョン ライブラリを、残りのドキュメントの上のこの場所にドラッグします。
ページ テンプレートを使用する
同じレイアウトで多くのページを作成している場合、1 つ以上のページテンプレートを作成しておくのは、実に時間の節約になります。あなたは常にパネルとコンテンツの表のように、同じマクロを追加する場合は、RSIから自分自身を保存し、テンプレートに入れて - あなたは1で始まり、しかし、あなたはあなたの効率を最大化するために必要な数を作ることができます。
すべてのスペースで利用可能なページ テンプレートを作成するには：
- Go to Administration menu
, then General Configuration - 左側の一覧からグローバル テンプレートおよびブループリントを選択します
- 右上にあるグローバル ページ テンプレートの追加ボタンを選択します。
- テンプレートページを作成し、保存を選択します。
For detailed info on page templates, see Create a template.
グローバル テンプレートおよびブループリントを使用したり、他の管理ページに素早く移動したりしたい場合は、「/」と入力してから、参照したい管理ページの名前を入力します。
下書きを作成する
ドキュメントで新しいページを作成する際、時間をかけて、保存しながら作成し、数人にレビューをしてもらい、フィードバックを受け取りたいことでしょう。つまり、このワークフローは、「ドラフト、レビュー、公開」となります。
不完全なページはユーザーに見せたくないでしょうし、多くのドキュメントは最終版とする前にレビューが必要となります。そこで、ページのドラフト作成とレビューを可能にする技術をご紹介します。
- Create a page and restrict its permissions
For example, you might restrict viewing to a group of people such as your team, or a few select individuals. On a public site, you might restrict viewing to staff members, so that the general public can't see the page. - ページのコンテンツを記述します。
- レビュアーとページを共有し、フィードバックを依頼します（レビュアーにページへの閲覧制限をかけないように注意してください）。
レビュアーはページの下部にコメントを追加したり、テキストをハイライト表示してインラインでコメントを追加したりできます。権限を付与すれば、レビュアーがページコンテンツを直接編集することも可能です。 - 準備が整ったら、以下の手順にしたがってページを公開します。
- ページからコメントを削除する。
- ページ制限を解除し利用者が閲覧できるようにする。
これでページが公開されました。今度は、スペース権限とサイト権限により、ページを閲覧および／または更新できる人を決定します。
リンクとアンカーを使用する
リンクを追加する
いずれのドキュメンテーション サイトにおいても、ページからページへリンクを設定できる必要があり、ページの特定セクションへのリンクも珍しくありません。Confluence ページにはどんな URL でも追加可能です。Confluence が自動的に検知し、リンクへと変換します。
Confluence サイトの他のページに URL を貼った場合、Confluence はリンクテキストをページ名として表示し、関連リンクに変換します。つまり、もし、ページ名が変更されても、Confluence がリンクを調整するためリンクが切れることはありません。
アンカーの追加とリンク
アンカーマクロを使用すると、他のページからリンクさせることができるアンカーをドキュメントに作成できます。ページのトップにアンカーを追加してあるので、トップへ戻るをクリックすると、ページのトップに戻ります。
同じページ内でリンクするマクロを追加するには：
- エディタに「
{anchor」と入力し、アンカー マクロを選択して、アンカーに名前 (例:top) を付けます。 - マクロにリンクするテキストを選択し、
Ctrl+K(Windows) またはCmd+K(Mac) と入力します (リンク ダイアログが開きます)。 - 左側のオプションから [詳細] を選択し、「
#」と入力してからアンカー名を続けます (例:#top)。
他ページのアンカーへリンクさせる際の概要全般とアンカーの利点については、リンクと アンカーに関するドキュメントを参照してください。
便利なマクロ
Confluence ではさまざまなマクロを用意しています。技術文書に非常に便利なマクロも数種類あります。いくつかご紹介します。
コンテンツ テーブル マクロ
The Table of Contents macro helps people navigate lengthy pages by summarizing the content structure and providing links to headings used on the page. The best part is, you don't need to do anything except add the macro; once you've added it, it'll automatically detect headings and add them to the table of contents.
ヒント・注意・情報・警告・パネルマクロ
ドキュメントを作成していると、よく、強調したい要素や読者の注意を惹き付けたい要素が出てきます。Confluence は、ヒント・情報・警告・注意・パネルマクロを備えています。コンテンツの特定の部分に読者の注意を惹き付けたい時に大変便利です。
今日のヒント
ヒントマクロを使用すれば、読者に役に立つヒントを提供できます。
ページ更新をトラッキングする
Confluence では、1 ページを複数の人間が更新することがよくあります。テクニカルライターは、レビュー中も公開後も、ドキュメントの状態を把握しておく必要があります。
ページやスペースをウォッチする
So that you know when changes are made, it's a good idea to watch pages or even the entire space. That way, when changes are made to pages you're watching, or someone comments on them, you'll get an email notification letting you know who changed what.
ドキュメンテーション スペースのページを開いているときに、右上にあるウォッチボタンを選択します。そのページのみをウォッチするか、スペースの全ページをウォッチするか選択できます。
ページ履歴を見る
Confluence は、ページが編集される度に新しいバージョンを作成します。ページ履歴は、更新日、作成者、コメントとともにすべてのバージョンを表示します。
ページ履歴を表示するには、該当のページに移動して、
ページ履歴ビューでは、以下の操作が可能です。
- ページの特定のバージョンのコンテンツを見る。
- 指定のバージョンに戻す（復元する）。
- 2 バージョン選択して比較し、変更箇所を確認する。
詳細な説明については、ページ履歴およびページ比較ビューを参照してください。
投稿者リストを表示する
If you want to see at a glance who's updated a page or pages, you can add the contributors macro. This macro displays a customizable list of people who've contributed by creating, editing, or, optionally, commenting on the page.
PDF エクスポートのカスタマイズ
ドキュメントを PDF で提供する予定がある場合は（メール、ダウンロード、印刷、その他の配信方法により）、タイトルページ、ヘッダー、フッターを追加することで PDF の表示をカスタマイズできます。
The process you take depends on whether you're trying to customize the PDF export for one space or for your whole site, so, if you're keen to make these changes, take a look at our page on Customize Exports to PDF for more detailed instructions.
その他の便利なツールとアプリ
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 apps available on the Atlassian Marketplace, most of which we use ourselves, which can extend the functionality of Confluence.
Marketplace には常に新しいアプリが追加されています。最新の情報については Marketplace をご参照ください。
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, by Atlassian Labs, 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 Data Center, 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.
Data Center バージョンには無料の Visio ビュアーも備わっているため、Microsoft Visio (.vsd) ファイルや Visio ステンシル (.vss) を表示できます。また、Visio へのエクスポートもサポートされています。
ドキュメント用テーマ (中止された機能)
Confluence はこれまで特にドキュメント用にテーマを提供してきました。このテーマは Confluence 6.0 では削除されました。
ヘッダーやフッター、およびサイドバーへのカスタム コンテンツの追加機能など、オリジナルのドキュメント用テーマ機能の多くが、Confluence のモダンな既定テーマで利用できるようになりました。ドキュメントのスペースでぜひご利用ください。