Confluence を技術文書の作成に使用する
Confluence は、技術文書の取り込み、配布、更新を支援する一連の機能やアドオンを備えた柔軟なプラットフォームです。独自の技術文書スペースを開き、ドキュメントのライフサイクルを管理する時間や労力を節約するためのヒントについて、以降で説明します。
ドキュメンテーション スペースを作成する
ドキュメントを開始するには
Confluence サイドバー の[スペース] >[すべてのスペースを表示] >[スペースを作成] の順に選択します。
Choose Documentation space (it'll give you a custom overview with a search box—the livesearch macro—to search just your documentation space, a recently updated macro, and a few other goodies) and hit Next
スペースに名前を付けて、作成 をクリックします。
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.
たとえば、製品のメジャー リリースごとにリリース ノートを作成して、各リリース ノートの前書きページを「新着情報」ページに含めるとします。各リリース ノートの前書きを抜粋マクロに、次に一連のリリース ノートの抜粋インクルード マクロを新着情報ページに追加します。前書きがさっと新着情報ページに表示されて、リリース ノートを更新すると新着情報も自動で更新されます。
抜粋: これらのページへの導入は、抜粋マクロにあります。
抜粋インクルード: 抜粋インクルード マクロです。
インクルード ページ マクロのもう 1 つの使用例を紹介します。アトラシアンのドキュメントに省略記号が表示されている場合 ([] > [コピー] など)、この省略記号はインクルード ページ マクロによるものです。その画像のみを含むページがあるので、省略記号が必要になるたびに、そのページを含めることができます。
小さな画像 1 つのためにインクルード ページ マクロを使用しているのは、UI 要素の変更に備えているためです。すべてのページに画像を添付した場合は、変更時に 50 ページの更新が必要になる可能性があります。インクルード ページ マクロを使用していれば、1 度の更新ですべての箇所を変更できます。また、この方法によってその画像を使用しているページ数を把握できます。 > [ページ情報] の順に移動すると、このページに対するリンクの数が表示されるため、画像を使用しているページ数を確認できます。
インクルードライブラリーを作成する（オプション）
どの Confluence ページのコンテンツでもインクルードできますが、「インクルードライブラリー」を作成して、再利用専用にコンテンツを保存するのもよいでしょう。インクルードライブラリーは、Confluence の特殊な機能ではありません。インクルードライブラリーのページは、他の Confluence ページとまったく同じです。再利用専用にコンテンツを保存する場所が必要な場合に使える、単なるテクニックなのです。
インクルードライブラリーを作成するには：
[作成] を選択して、スペースに新しいページを作成します。
適切なタイトルを入力します。ここでは「_ConfluenceInclusions」とします (タイトルの前のアンダースコアは、このページが特別であることを知らせるのに役立ちます)。
コンテンツを入力し、ページを公開します。アトラシアンでは、インクルード ライブラリーの目的とコンテンツを再利用する方法を説明するテキストを入力しています。
サイドバーに表示されるスペース名の横で [その他のアクション (•••)] > [スペース設定] の順に選択します。
[コンテンツ] メニューを開いて[並び替え] を選択します。
山括弧 [>] を選択して、ページ ツリーを展開します。
スペース概要の上に新しいページをドラッグします。
新しいインクルード ページに移動して [作成] を選択し、再利用可能なコンテンツを含む子ページを追加します。
インクルージョン ライブラリの場所: インクルージョン ライブラリを、残りのドキュメントの上にドラッグします。
スペースの「ルート」にページを移動したため、スペース のページ セクションには表示されません。しかし、インクルードライブラリのページは普通の Confluence のページであるため、他の検索には表示されます。
ページ テンプレートを使用する
同じレイアウトで多くのページを作成している場合、1 つ以上のページテンプレートを作成しておくのは、実に時間の節約になります。あなたは常にパネルとコンテンツの表のように、同じマクロを追加する場合は、RSIから自分自身を保存し、テンプレートに入れて - あなたは1で始まり、しかし、あなたはあなたの効率を最大化するために必要な数を作ることができます。
すべてのスペースで利用可能なページ テンプレートを作成するには：
右上隅の歯車アイコン () を選択して Confluence 管理を開きます。
左側のナビゲーションで「設定」>「設定」を探します。
「グローバル テンプレートとブループリント」を選択します。
右上にある「グローバル ページ テンプレートを追加」ボタンを選択します。
テンプレート・ページを作成し、「保存」を選択します。
For detailed info on page templates, see Blueprints and User Created Templates.
[グローバル テンプレートとブループリント] や他の管理ページにすばやく移動するには、/ キーを押して、探している管理ページの名前を入力し始めます。
下書きを作成する
ドキュメントで新しいページを作成する際、時間をかけて、保存しながら作成し、数人にレビューをしてもらい、フィードバックを受け取りたいことでしょう。つまり、このワークフローは、「ドラフト、レビュー、公開」となります。
不完全なページはユーザーに見せたくないでしょうし、多くのドキュメントは最終版とする前にレビューが必要となります。そこで、ページのドラフト作成とレビューを可能にする技術をご紹介します。
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 instance, you might restrict viewing to staff members, so that the general public can't see the page.
ページのコンテンツを記述します。
Share the page with your reviewers and ask them for feedback. (Make sure you haven't restricted them from seeing the page!) The reviewers can add comments to the bottom of the page or highlight text to add a comment inline. If you give them permission, they can also edit the page content directly.
準備が整ったら、以下の手順にしたがってページを公開します。
ページからコメントを削除する。
ページ制限を解除し利用者が閲覧できるようにする。
これでページが公開されました。今後、ページの閲覧や更新が可能なユーザーは、スペース権限とサイト権限によって決まります。
リンクとアンカーを使用する
リンクを追加する
どのようなドキュメンテーション・スペースでも、あるページから別のページへ、さらにはページ上の特定のセクションへリンクできるようにすることが不可欠です。Confluence ページには任意の URL を追加でき、Confluence はそれを自動的に検知し、リンクに変換します。
Confluence インスタンスに別のページの URL を貼り付けると、Confluence はリンク・テキストをページ名として表示し、相対リンクに変換します。つまり、ページ名が変更された場合、Confluence はリンク切れにならないように、そのリンクを調整します。
アンカーの追加とリンク
Confluence の各見出しは、ページ上の特定の場所にリンクするためのアンカーとして使用できます。
便利なマクロ
Confluence ships with a great range of macros, and there are a few that are particularly useful in technical documentation. Here's a few:
コンテンツ テーブル マクロ
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.
情報パネル
Often when creating documentation, there are elements of a page that you want to highlight or draw the the viewers' attention to. Use the panel element to create info, warning, success, and other custom info panels.
ページ更新をトラッキングする
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 instance, 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 を拡張できます。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 allows you to create and insert diagrams within your Confluence Cloud instance. Quickly draw flowcharts, wireframes, UML diagrams, mind maps, and more inside our feature-rich editor.
テクニカル ドキュメントとしての Confluence をお試しください。
この内容はお役に立ちましたか?