Confluence を技術文書の作成に使用する
Confluence は、技術文書の取り込み、配布、更新を支援する一連の機能やアドオンを備えた柔軟なプラットフォームです。独自の技術文書スペースを開き、ドキュメントのライフサイクルを管理する時間や労力を節約するためのヒントについて、以降で説明します。
ドキュメンテーション スペースを作成する
ドキュメントを開始するには
Confluence のナビゲーションで、[スペース] > [すべてのスペースを表示] > [スペースを作成] の順に選択します。
[文書のスペース] を選択して (これによって検索ボックス (livesearch マクロ) を備えたカスタム ホームページが提供されて、最近の更新マクロなどを検索できます) [次へ] をクリックします。
スペースに名前を付けて、作成 をクリックします。
Confluence はスペース キーを自動的に作成してスペース概要を作成します。概要はいつでも自由にカスタマイズしてください。ホームページの外観はお客様の思いどおりです!
コンテンツの再使用による時間の節約
単語、文、段落や画像、製品のバージョン番号、その他何でも、ドキュメント スペースで何回も使用するつもりであれば、それを 1 回作成しておいて、あとで好きなだけページに含める (インクルードする)、またはヘッダーやフッターに使用できます。インクルードは、同じことを何度も入力する手間を省くだけでなく、変更がより簡単になります。47 か所で情報を更新するよりも、1 か所で更新する方がはるかに楽です。
コンテンツの再利用を可能にするマクロは 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.
たとえば、製品のメジャー リリースごとにリリース ノートを作成して、各リリース ノートの前書きページを「新着情報」ページに含めるとします。各リリース ノートの前書きを抜粋マクロに、次に一連のリリース ノートの抜粋インクルード マクロを新着情報ページに追加します。前書きがさっと新着情報ページに表示されて、リリース ノートを更新すると新着情報も自動で更新されます。
抜粋: これらのページへの導入は、抜粋マクロにあります。
抜粋インクルード: 抜粋インクルード マクロです。
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 ページとまったく同じです。再利用専用にコンテンツを保存する場所が必要な場合に使える、単なるテクニックなのです。
インクルードライブラリーを作成するには：
[作成] を選択して、スペースに新しいページを作成します。
適切なタイトルを入力します。ここでは「_ConfluenceInclusions」とします (タイトルの前のアンダースコアは、このページが特別であることを知らせるのに役立ちます)。
コンテンツを入力し、ページを公開します。アトラシアンでは、インクルード ライブラリーの目的とコンテンツを再利用する方法を説明するテキストを入力しています。
サイド バーで [スペース設定] を選択します。
[ページを管理] カードから [並び替え] を選択します。
山括弧 [>] を選択して、ページ ツリーを展開します。
スペース概要の上に新しいページをドラッグします。
新しいインクルード ページに移動して [作成] を選択し、再利用可能なコンテンツを含む子ページを追加します。
インクルージョン ライブラリの場所: インクルージョン ライブラリを、残りのドキュメントの上にドラッグします。
スペースの「ルート」にページを移動したため、スペース のページ セクションには表示されません。しかし、インクルードライブラリのページは普通の Confluence のページであるため、他の検索には表示されます。
ページ テンプレートを使用する
同じレイアウトで多くのページを作成している場合、1 つ以上のページテンプレートを作成しておくのは、実に時間の節約になります。あなたは常にパネルとコンテンツの表のように、同じマクロを追加する場合は、RSIから自分自身を保存し、テンプレートに入れて - あなたは1で始まり、しかし、あなたはあなたの効率を最大化するために必要な数を作ることができます。
すべてのスペースで利用可能なページ テンプレートを作成するには：
Select the wheel icon () in the top-right corner to open Confluence administration.
左側のナビゲーションで「設定」>「設定」を探します。
「グローバル テンプレートとブループリント」を選択します。
右上にある「グローバル ページ テンプレートを追加」ボタンを選択します。
テンプレート・ページを作成し、「保存」を選択します。
ページ テンプレートの詳細については「ブループリントとユーザーが作成したテンプレート」をご参照ください。
To get to Global templates and blueprints, or any other admin page quickly, press / and start typing the name of the admin page you're looking for.
下書きを作成する
ドキュメントで新しいページを作成する際、時間をかけて、保存しながら作成し、数人にレビューをしてもらい、フィードバックを受け取りたいことでしょう。つまり、このワークフローは、「ドラフト、レビュー、公開」となります。
不完全なページはユーザーに見せたくないでしょうし、多くのドキュメントは最終版とする前にレビューが必要となります。そこで、ページのドラフト作成とレビューを可能にする技術をご紹介します。
ページを作成し、その権限を制限します。たとえば、閲覧をチームなどのユーザー・グループに制限したり、特定のユーザーを指定したりできます。公開インスタンスの場合、閲覧をスタッフ・メンバーのみに制限すれば、そのページは一般の人には表示されません。
ページのコンテンツを記述します。
レビュアーとページを共有し、フィードバックを依頼します (レビュアーにページへの閲覧制限をかけないようにご注意ください)。レビュアーはページの下部にコメントを追加したり、テキストを選択してインラインでコメントを追加したりできます。権限を付与すれば、レビュアーがページのコンテンツを直接編集することも可能です。
準備が整ったら、以下の手順にしたがってページを公開します。
ページからコメントを削除する。
ページ制限を解除し利用者が閲覧できるようにする。
これでページが公開されました。今後、ページの閲覧や更新が可能なユーザーは、スペース権限とサイト権限によって決まります。
リンクとアンカーを使用する
リンクを追加する
どのようなドキュメンテーション・スペースでも、あるページから別のページへ、さらにはページ上の特定のセクションへリンクできるようにすることが不可欠です。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 (サポート対象外)
The Copy Space for Confluence app 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.
このアプリは、現在のスペースを特定のタイミングでアーカイブする必要がある場合にも便利です。例えば、製品のとあるバージョンから次のバージョンへ移行する際などに、スペースをコピーし、新しい名前を付け、任意の場所に保存しておけば、既存のスペースを失うことはありません。
Copy Space アプリでは現在、ページ履歴、ブログ投稿およびメールのコピーは行われません。
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 Diagrams Connector を使用すると、Confluence Cloud インスタンス内で図を作成して挿入できます。機能豊富なエディターで、フローチャート、ワイヤーフレーム、UML 図、マインド・マップなどを簡単に作成できます。
テクニカル ドキュメントとしての Confluence をお試しください。
この内容はお役に立ちましたか?