マニュアルなどの技術ドキュメントを維持管理する上で大切なのは、最初からメンテナンスを考慮した計画と設計を行い、メンテナンスに真剣に取り組むことです。この記事では、ドキュメント オーサリング ツール「MadCap Flare」のコンサルタントである Nita Beck 氏が、Flare プロジェクトを例に、メンテナンスしやすい技術文書にするためのベスト プラクティスを紹介します。
- 設計の計画を立てる
- フォルダー構造と命名規則を決める
- トピック テンプレートや「スターター」スニペットを作成する
- コンテンツ、スタイルシート、その他のプロジェクト ファイル内にメモを残す
- プロジェクトを整理整頓する
- ライター向けのガイドを作成する
経験から言えること
15 年以上にわたり MadCap Flare コンサルタントとして多くのプロジェクトに関わってきた経験から、よく構成されていてすぐに理解できるプロジェクトもあれば、そうではないものも多いのが現実です。Flare プロジェクト内のどのファイルが実際に使用されていて、どれが不要なファイルなのか、頭を抱えることがよくあります。
これまで、ターゲット、目次、トピック、画像、その他のコンテンツ ファイルが大量に含まれているプロジェクトを数多く見てきましたが、それらは結局、古いツールから移行した際の残骸であったり、実験的に作成されたものだったりします。
技術文書のメンテナンスが重要な理由
テクニカル ライターが作成するデジタル ファイルは、倉庫の在庫や工場にある設備と同じくらい重要な企業の資産です。これらのファイルは費用をかけて作成された価値があるものであり、適切に管理されるべきです。だからこそ、技術文書のメンテナンスは、あらゆる組織にとってビジネス プロセス要件であるべきです。
テクニカル ライターには、自分が生み出したデジタル資産を、最高の状態で管理・保護するプロとしての義務があります。
技術文書は誰のためのものか?
テクニカル ライターは、エンドユーザーのためにドキュメントを設計・開発します。ドキュメントのブランディングや構成を考慮し、分かりやすく、アクセスしやすいナビゲーションを目指します。エンドユーザーがあらゆるデバイスで利用できるよう、レスポンシブ デザインに対応したスタイルシートやスキン要素を設計します。また、ローカライズすることも考慮し、翻訳しやすいコンテンツの作成に努めます。ソフトウェア アプリケーションのヘルプ システムの場合は、状況に応じて適切なコンテンツにアクセスできるよう、開発者との連携が必要になる場合もあります。
つまり、エンドユーザー、マーケティング担当者 (ブランディング管理)、翻訳者、開発者を考慮して設計しています。
しかし、最も重要な存在は、現在そして将来の私たちライター自身です。「メンテナンスのしやすさ」も設計の重要な目的であるべきです。
メンテナンスを考慮した設計戦略
以下は、私の経験から導き出された Flare プロジェクトの設計 (および開発) におけるベスト プラクティスです。
- メンテナンスの容易さ – 特に、プロジェクトを引き継ぐ、または将来的にプロジェクトに参加するライターにとってメンテナンスが容易であることは重要です。
- 拡張の容易さ – たとえば、当初想定していなかった新しい出力形式の生成が必要になった場合でも、容易に対応できる必要があります。
全体的な原則は以下のとおりです。
- 熟考する
- 「ゴミ」を放置しない
- 記録に残す
- 後任者に配慮する
ベスト プラクティス 1: 分析と計画
新しい Flare ベースの技術文書プロジェクトを開始する際は、以下の点に注目します。
- プロジェクトの構造: 特にフォルダー構成。
- ルール: フォルダーやファイル名に使う「略語」のルール。
- 現在と将来のニーズ: 特に出力形式やローカライズに関するニーズ。
- メンテナンス、レビュー、ソース コントロールのワークフロー。
マインドマップなどを使用して、フォルダー構造や関係性を視覚化すると、命名規則などをあらかじめ検討するのに役立ちます。
スイムレーン図も、ドキュメント作成ワークフローやプロジェクト間の関係性を視覚化するのに役立ちます。
ほとんどのプロジェクトでは、分析および計画段階で検討したすべての事項が、Word または Google ドキュメントを使用して、設計計画書としてまとめられます。
ベスト プラクティス 2: プロジェクトを整理整頓する
Flare でドキュメント作成プロセスを開始する際に、以下のことを習慣にしてましょう。
- 計画した命名規則とフォルダー構造を忠実に守る。
- すべてのものの位置を決め、それぞれのものをその場所に置く。
- 常に整理整頓を心がける。
まずは命名規則から始め、分かりやすい名前にしましょう!
たとえば、以下の表の左側に示すようなトピック ファイル名は、長年そのコンテンツに携わってきたメンバーにとっては、既存のドキュメントの内容を理解する上で意味のあるものかもしれません。しかし、チームに新しく加わったメンバーにとっては、どの章に属するトピックなのか、どのような順序なのかが分かりづらいです。この例では、表の右側に示すような最初の見出しのフレーズに合わせたファイル名に変更することで、より分かりやすくなります。
|
以前のファイル名 |
分かりやすいファイル名 |
|---|---|
|
1-1-1.htm |
purpose-of-this-order.htm |
|
1-1-2.htm |
audience.htm |
|
1-1-3.htm |
where-to-find-this-order.htm |
|
1-1-4.htm |
what-this-order-cancels.htm |
フォルダー構成は「深すぎず、浅すぎず」
すべてのものに適切な名前を付け、適切な場所に配置すべきです。コンテンツ ファイルは、親フォルダー直下に保存しないようにします。たとえば、すべてのトピック ファイルを Topics フォルダー直下に配置すると、プロジェクトが大きくなるにつれて、ファイル一覧が非常に長くなります。代わりに、サブフォルダーを使ってトピック ファイルを整理することをお勧めします。ただし、階層を深くしすぎないように注意が必要です。階層が深すぎるフォルダー構造は、浅すぎる構造と同様に扱いにくくなる可能性があります。
たとえば、オンライン ヘルプを生成するある長期プロジェクトでは、以下のようにトピックをトピックの種類ごとに整理しています。
- コンテンツ
- …
- トピック
- コンセプト
- con-about-abc.htm
- con-about-xyx.htm
- FAQ
- faq-how-do-i-abc.htm
- faq-why-does-this-happen-at-xyz.htm
- ランディング
- リファレンス
- タスク
- コンセプト
オンライン コンテンツと PDF の両方を出力する別のプロジェクトでは、出力タイプごとに整理し、さらにその中で章ごとに整理しています。
- コンテンツ
- …
- システム アーキテクチャー
- 概要
- about-sysarch-manual.htm
- acknowledgments-sysarch.htm
- はじめに
- _ch-intro.htm
- programming-model.htm
- keywords.htm
- 詳細
- メモリ
- 概要
最近引き継いだあるプロジェクトでは、すべてのトピックがそれぞれ独自のサブフォルダーに格納され、関連する画像もその中に含まれていたため非常に扱いにくく、チームの作業効率と生産性に悪影響を及ぼしています。このプロジェクトでは今後、検索のしやすさを考慮して、フォルダー構造 (とファイル名) を全面的に見直す予定です。
「ゴミ」を放置しない
ある非常に大規模な Flare プロジェクトでは、元々多数の RoboHelp プロジェクトだったものが、1 つの巨大な Flare プロジェクトにまとめられたことで、Flare の動作が重くなり、チームは開発プロセスに不満を募らせていました。
1 週間かけてこのプロジェクトの状態を分析した結果、次のような「残骸」が大量に見つかりました。
- 何年も前の「変更履歴」が残ったままのファイル。
- 連続するインポート処理中に発生した重複ファイル。同じロゴ画像が 35 個も含まれていたり、使用されていないスタイルシートやスキン ファイルも多数存在。
- Flare の使い方を習得する際に実験的に作成したターゲット、目次、スタイルシート、その他のファイル。
- 以前の製品リリースで使用され、現在は使用されていない数百もの画像ファイルを含むフォルダー。
- 不要でありながら、クライアントが削除することをためらっていた数百もの未使用トピック。
- サブフォルダーに深くネストされた、現在は使用されていない数百ものターゲット。
- 対処されることなく放置された数百ものリンク切れやブックマーク切れ。
- その他…
このケースでは、プロジェクトを整理整頓することで、チームはより快適に、効率的に作業を進められるようになりました。
このケースから、すべてのものに適切な名前を付けて、決められた場所に置くとことが重要であることが分かります。そして、不要になったファイルは、勇気を持って捨てましょう。
ベスト プラクティス 3: 使いやすい「ウィジェット」を作成する
新しいコンテンツをすぐに作成できるように、ファイル テンプレート、スターター スニペット、自動入力候補機能など、使いまわしができるウィジェットを用意しておきます。
ファイル テンプレート
頻繁に作成するファイルの種類や、コンテンツ開発プロセスにおいて「あらかじめ準備しておきたい」ファイルの種類を予測し、型を作っておきます。
- トピック テンプレート (参照トピックやタスク トピックなど): プレースホルダー コンテンツとライター向けガイドを含めます。
- 目次テンプレート: プレースホルダーの目次項目を含めます。
- ターゲット テンプレート: 特定のオプションをあらかじめ設定しておきます。
- インポート ファイル テンプレート: インポート ルールをあらかじめ定義しておきます。
通常、これらのファイルは Flare プロジェクト内の同じ種類のファイルと同じ場所に保存します。ライターはこれらのファイルをコピー & ペーストして名前を変更し、コンテンツの作成を開始できます。これらのファイルは、MyFolders フォルダーに保存したり、共有フォルダー内の外部リソースとして保存することも可能です。
スターター スニペット
よく使う定型文や警告文などのスニペットを作成しておくことで、ライターはトピックにスターター スニペットを挿入し、テキストに変換して、すばやくコンテンツを編集できます。
自動入力候補
スニペットを含め、自動入力候補機能をオンにすると、ライターがトピックまたはスニペットに文字を入力した際に、Flare は変数、スニペット、および自動入力候補リスト (単純なテキスト文字列のリスト) で見つかった一致するテキスト文字列を 1 つ以上提案します。ライターは提案された候補の中から選択して、作業を進めることができます。
ベスト プラクティス 4: プロジェクトを文書化する
将来のために、プロジェクト管理の記録を残します。
プロジェクトを文書化するためのアイデアをいくつか紹介します。
こまめにメモを残す
Flare には、CSS スタイルや変数を作成する際など、コメント フィールドが用意されている箇所が数多くあります。作成したものの目的についてコメントを追加しておくと、後で必ず役に立つでしょう。
ライター向け ReadMe を作成する
ライター向け ReadMe を作成し、プロジェクトの重要なポイントを記入します。たとえば、以下のような項目を含めます。
- プロジェクトがサポートするソフトウェア製品
- プロジェクトが生成するターゲット
- コンテンツ エクスプローラの構造
- トピック タイプ (概念、リファレンス、タスクなど)
- ローカル インデックス リンク
- グローバル変数とローカル変数
プロジェクト内に「ライター向けハンドブック」を作成する
ReadMe だけで終わらせず、もっと踏み込んだ内容をプロジェクト内に用意することもできます。具体的には、メンテナンスに必要な知識をまとめたページや、そのための専用の目次、出力設定 (ターゲット) などをプロジェクトの中に直接作ってしまうのです。たとえば、作成したマニュアルを Zendesk (サポート サイト用のツール) へ公開する具体的な操作手順について説明した「ライター向けページ」をプロジェクト内に作成します。
独立した「ライター向けガイド専用プロジェクト」を作成する
さらに一歩進めて、マニュアル作成のルールや慣習だけをまとめた、独立したプロジェクトを作ることもできます。その場合、この専用プロジェクトのフォルダー構成、名前、デザイン設定 (スタイルシート) は、製品マニュアルと同じルールに従って作成するようにします。
ガイドの内容は、必要に応じて決めることができます。たとえば、あるクライアントは、部門全体の文章作成ガイドライン、ソース管理方法、画像の管理ルール、ローカライズの手順、関連ツールの使い方などを文書化しています。
このような社内用ガイドは、新しくチームに加わったメンバーの研修 (オンボーディング) にも役立ちます。これを見れば、チーム独自のルールをすぐに理解し、スムーズに作業に入ることができます。
あるクライアントでは、これを「ライター向けライブラリ」と呼び、社内の複数のチームがいつでも Web 上で閲覧できるように共有しています。
Flare を使わずに Flare プロジェクトを文書化する方法
Flare を使わずに、Confluence、SharePoint、共有 OneNote ノートブックなどのツールを使用して Flare プロジェクトのドキュメントを作成することも可能です。
プロジェクトを始める前に Word や Google ドキュメントで作成した「設計計画書」を、「メンテナンス ガイド」へと拡張させてることもできます。
最後に
Flare プロジェクトのメンテナンスを容易にするためのあらゆる計画や設計も、プロセスをしっかりと文書化し、それを遵守しなければ意味がありません。定期的に「大掃除」を行い、使用されていないファイルがないか確認し、不要になったファイルや実験的なファイルは削除してください。そして何よりも重要なのは、「将来のライター (それは数ヶ月後のあなたかもしれません)」が困らないためのガイドを作成することです。
製品の情報や、ブログの最新情報をお届け！ エクセルソフト ニュースの購読お申し込みはこちらから。
この資料は、MadCap Software の Web サイトで公開されている「How to Maintain Your Technical Documentation」の日本語参考訳です。
This blog first appeared on the MadCap Software website. MadCap Software is the leading software provider for end-to-end documentation solutions.
