Confluence で技術文書を開発する
スペースのテーマを「ドキュメンテーション」に設定したい場合、サイドバーの下部からスペースツール > ルックアンドフィールを選択したあと、テーマを選択し、ドキュメンテーション テーマを選択します。
コンテンツの再使用により時間を節約する
単語、文、段落や画像、製品のバージョン番号、その他何でも、ドキュメンテーション スペースで何回も使用するつもりであれば、それを 1 回作成しておいて、あとで好きなだけページにインクルードできます（またはヘッダーやフッターに使用できます）。インクルードは、同じことを何度も入力する手間を省くだけでなく、変更がより簡単になります。47 か所で情報を更新するよりも、1 か所で更新する方がはるかに楽です。
コンテンツの再利用を可能にするマクロは 3 つあります：
- 抜粋マクロ： ページ上で再利用可能な部分を定義、または「抜粋」します － このマクロの中にコンテンツを追加すれば、好きなだけページで再利用できます。
- 抜粋インクルード マクロ (
excerpt-include) は別のページからの抜粋に含まれるコンテンツを含めます。 - ページ インクルード マクロ (
include) は、ページのコンテンツ全体を別のページに含めます。
例えば、製品のメジャーリリースごとにリリースノートを作成し、各リリースノートの前書きを「新着情報」ページにインクルードしたいと考えているとします。各リリースノートの前書きを抜粋マクロに入れ、次にリリースノートのセットごとの抜粋インクルードマクロを新着情報ページに追加します。前書きは魔法のように新着情報ページに表示され、リリースノートを更新すると、新着情報は自動的に更新されます。
もう 1 つの例は、私たちがインクルードページマクロをよく利用する方法の 1 つです。ドキュメントに省略記号（ 
）が表示されるとき、－ 例えば、 > コピーに移動します － このような場合はいつもそうですが、この省略記号は実はインクルードページマクロです。その画像のみのページがあるため、省略記号が必要になるたびに、そのページをインクルードします。
小さな画像 1 つのためにインクルードページマクロを使用しているのは、UI 要素の変更に備えているためです。すべてのページに画像を添付した場合、変更があったときに 50 ページの更新が必要になる可能性があります。インクルードページ マクロを使用していれば、1 度の更新ですべての箇所を変更できます。この方法を使うと、その画像を使用しているページ数を知ることもできます。 > [ページ情報] に移動すると、このページへのリンクの数から、画像を使用しているページ数を確認できます。
インクルードライブラリーを作成する（オプション）
どの Confluence ページのコンテンツでもインクルードできますが、「インクルードライブラリー」を作成して、再利用専用にコンテンツを保存するのもよいでしょう。インクルードライブラリーは、Confluence の特殊な機能ではありません。インクルードライブラリーのページは、他の Confluence ページとまったく同じです。再利用専用にコンテンツを保存する場所が必要な場合に使える、単なるテクニックなのです。
インクルードライブラリーを作成するには：
- 作成を選択し、スペースに新しいページを作成します
- 適切なタイトルを入力します。ここでは「_ConfluenceInclusions 」を使用します（タイトルの前のアンダースコアは、このページが特別であることを知らせるのに役立ちます）
- コンテンツを入力し、ページを保存します
私たちの場合、インクルードライブラリーの目的とコンテンツを再利用する方法を説明するテキストを入力しています - スペースツール > ページの並べ替え (または、ドキュメンテーションテーマを使用している場合、 ブラウズ > ページ）を選択し、 新しいページをスペースホームページの上にドラッグします
- 新しいインクルードページに移動して、作成を選択し、再利用可能なコンテンツを含む子ページを追加します
スペースのルートにページを移動したため、 サイドバーのページツリーには表示されません。しかし、インクルードライブラリのページは普通の Confluence のページであるため、他の検索には表示されます。
ページ テンプレートを使用する
同じレイアウトで多くのページを作成している場合、1 つ以上のページテンプレートを作成しておくのは、実に時間の節約になります。パネルやコンテンツの表のように、常に同じマクロを追加している場合、それをテンプレートに入れて、反復操作のストレスから自分を守りましょう － テンプレート作成は 1 つから始められ、必要な数だけ作って効率を最大化できます。
すべてのスペースで利用可能なページ テンプレートを作成するには：
- 移動
> General Configuration - 左側の一覧からグローバル テンプレートおよびブループリントを選択します
- 右上にあるグローバル ページ テンプレートの追加ボタンを選択します。
- テンプレートページを作成し、保存を選択します。
ページ テンプレートの詳細については、テンプレートを作成する を参照してください。
グローバル テンプレートおよびブループリントや、他の管理ページに素早く移動したい場合は、「/」を入力してから、参照したい管理ページの名前を入力します。
下書きを作成する
ドキュメントで新しいページを作成する際、時間をかけて、保存しながら作成し、数人にレビューをしてもらい、フィードバックを受け取りたいことでしょう。つまり、このワークフローは、「ドラフト、レビュー、公開」となります。
不完全なページはユーザーに見せたくないでしょうし、多くのドキュメントは最終版とする前にレビューが必要となります。そこで、ページのドラフト作成とレビューを可能にする技術をご紹介します。
- ページを作成し、権限を制限します。
例えば、閲覧をチームのピープルに制限したり、数人のメンバーに限定したりできます。パブリックサイトでは、閲覧をスタッフメンバーにのみ制限すれば、一般の人々はページを見ることができません。 - ページのコンテンツを記述します。
- レビュアーとページを共有し、フィードバックを依頼します（レビュアーにページへの閲覧制限をかけないように注意してください）。
レビュアーはページの下部にコメントを追加したり、テキストをハイライト表示してインラインでコメントを追加したりできます。権限を付与すれば、レビュアーがページコンテンツを直接編集することも可能です。 - 準備が整ったら、以下の手順にしたがってページを公開します。
- ページからコメントを削除する。
- ページ制限を解除し利用者が閲覧できるようにする。
これでページが公開されました。今度は、スペース権限とサイト権限により、ページを閲覧および／または更新できる人を決定します。
リンクとアンカーを使用する
リンクを追加する
いずれのドキュメンテーション サイトにおいても、ページからページへリンクを設定できる必要があり、ページの特定セクションへのリンクも珍しくありません。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 summarising 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 ページを複数の人間が更新することがよくあります。テクニカルライターは、レビュー中も公開後も、ドキュメントの状態を把握しておく必要があります。
ページやスペースをウォッチする
変更があった際、それがわかるように、ページやスペース全体をウォッチするとよいでしょう。ウォッチしているページに変更やコメントが加えられると、誰がどのような変更を行ったかメールで通知されます。
ドキュメンテーション スペースのページを開いているときに、右上にあるウォッチボタンを選択します。そのページのみをウォッチするか、スペースの全ページをウォッチするか選択できます。
ページ履歴を見る
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 customisable 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 customise 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 Customise 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 add-ons available on the Atlassian Marketplace, most of which we use ourselves, which can extend the functionality of Confluence.
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 へのエクスポートもサポートされています。