日頃より、弊社をご愛顧いただきまして誠にありがとうございます。この度、ゴーツーラボ 株式会社が営むアトラシアン製品ライセンスの販売および SI サービスの提供事業をリックソフト 株式会社に譲渡することで合意し、事業譲渡契約を締結する運びとなりました。詳細については、「事業譲渡に関するお知らせ」をご参照ください。

Wiki を活用したテクニカル ライティング : テクニカル コミュニケーターが解説する手法と理由

2010-11-17 (Wed)  •  By 伊藤  •  活用のヒント  •  Confluence 翻訳

今回の記事は、「Technical Writing in a Wiki: Technical Communicators Explain How & Why 」の弊社翻訳版です。原文と差異がある場合は、原文の内容が優先されます。

今回の記事は、Wiki (ウィキ) を活用したテクニカル ライティングを主題とした、アトラシアンのテクニカル ライティング チームによるシリーズ投稿の第 1 弾です。この投稿では、テクニカル ドキュメントのニーズに関し、Wiki がよい解決策である理由について解説します。第 2 弾以降の投稿では、Wiki 上でのドキュメントの作成、公開、構造化および管理について取り上げます。

私がアトラシアンに入社した時点で Wiki は 10 年以上の歴史がありました。しかし、ドキュメント作成に Wiki を活用することはそれまで考えたこともありませんでした。あなたも同様かもしれません。でもその考えを捨てて、私と一緒に Wiki を活用してみましょう。Wiki は単なるオンライン百科事典ではありませんよ。

「Wiki は面白いけど、まじめなドキュメントには向いていないな」

Wiki は基本的に、複数ユーザーによるコンテンツの追加、修正および削除が簡単に行える Web サイトです。そのため、あなたのチームが協力して資料作成をするのに向いています。しかし、作成中の状態で外部に公開するわけにはいきません。少なくとも私はそう考えています。

実のところ、Wiki は従来の出版や CMS ツール同様、ドキュメント作成のための包括的スイートとしての機能を備えています。Wiki では、ドキュメントのバージョン管理、コンテンツの再利用や構造化、リリース管理、シングル ソーシング、公開、その他のことが可能です。これらのトピックの詳細については今後の投稿で取り上げる予定です。今回は Wiki を活用したドキュメント作成に関し、私が気が付いたメリットを紹介します。

1) あなた (テクニカル ライター) にとって都合がよい

出版の際にいくつも段階を経るような従来の執筆ツールを使用している場合、Wiki 上でのドキュメントの作成は画期的かもしれません。公開済みドキュメント ページ上の間違いを修正したい場合はどうでしょう? 該当ページを開き、編集し、そして保存するだけです。ただそれだけです。

HTML や XML を利用する場合に比べ、編集作業もより容易です。Confluence など、企業向け Wiki の多くはリッチ テキスト エディタを同梱しており、複雑なマークアップとの格闘が必要ありません。ドキュメントの表示をくずしているタグの追跡ではなく、執筆活動に専念できることは気が楽です。

Wiki で簡略化されるのはドキュメント作成や公開作業だけではありません。技術ドキュメント作成のための情報の収集は、多くの場合、製品マネージャー、開発者および私自身の共同努力を必要とします。初期の下書きを作成してレビューすることで、有益なフィードバックを数多く得られます。他のスタッフがそのページにコメントを残したり、下書きそのものをアップデートしたりすることが可能だからです。その後、必要に応じてフィードバックを選択/採用したり、変更を戻したりできます。

2) 顧客にとって都合がよい

多くの Wiki は従来のドキュメント作成ツールを備えており、時間のない顧客による必要な情報の検索を手助けします。例えば、強力な検索エンジン、タグ/ラベル、ブレッド クラム/ナビゲーション ツリーなどです。Wiki はこれら機能を大幅に拡張し、顧客によりリッチなコンテンツを提供することが可能です。コンセプトの説明よりもデモの方が分かりやすい場合、あなたのドキュメントに動画の追加をしてみましょう。でも、複雑なコマンドを記述する必要はありません。プロセス図をあなたの Wiki ページに埋め込むだけです。多くの標準的な Wiki では、これら画期的な機能の追加にアドオンやプラグインを利用することができます。

顧客に異なる形式でドキュメントを提供する場合でも心配はありません。多くの Wiki では、ドキュメントを各種形式にエクスポートするオプションが提供されています。弊社ではドキュメントを PDF、HTML ならびに XML 形式にエクスポートしています。各エクスポート形式に対し、異なるスタイルも適用可能です。これにより、対象読者に適した形にドキュメントをカスタマイズできます。

Wiki 上で管理されているドキュメントは顧客サポートの改善にも役立ちます。弊社サポート スタッフは頻繁にドキュメントの更新や追加を行っており、顧客が最新情報に触れられるようにしています。それ以外にも、Wiki は別の貴重なフィードバック チャンネルを顧客に提供可能です。ページに追加されたコメントは、たびたび、そのドキュメントもしくはアプリケーションそのものに対する問題に気づかせてくれます。

あなたの会社にとって都合がよい

自社のドキュメント用 Wiki 上に顧客がクレームのコメントを追加することが心配ですか? スパム業者による大量の迷惑コメントが心配ですか? 一方で、別の考え方もできます。顧客が Wiki 上の他の顧客の質問に答えたり、外部開発者がコード サンプルを追加することでドキュメントに肉付けを行ったり、パートナーがボランティアで新しいドキュメントを作成したりするかもしれません。また、よく管理されたドキュメント用 Wiki は顧客コミュニティの成長を促進します。優れた企業向け Wiki は、きめ細かな権限、CAPTCHA およびスパム フィルターなどのツールを備えており、あなたのコミュニティがドキュメントに安全に関われるようになっています。多くの組織ではすでに自身のドキュメントを Wiki 上で管理しています。Anne Gentle 氏による、ドキュメント Wiki の一覧 をご確認ください。

最後に、問題点。いくつかの Wiki は有償である代わりに、他の Wiki よりも多くの機能を備えています。例えば、企業ドキュメントを Wiki 上で管理する場合、通常、きめ細かな権限が必要となります。この機能はオープンソース Wiki では恐らく得られないでしょう。一方で、価格競争力のある Wiki ソリューションに驚かれるかもしれません。テクニカル ライターが上述のメリットの恩恵を受けられる場合、あなたの組織におけるドキュメント作成プロセス全体を合理化させることができます。あなたの組織は、最終的には現在ドキュメント作成に支払っている費用の何分の一かを支払うだけで済むかもしれません。

投資する価値はありますし、弊社もお手伝いします。今後数週間かけて、アトラシアン テクニカル ライティング チームはシリーズ投稿を掲載します。それぞれで高度な話題を取り扱います。次週、Giles Gaskell が出版に関する詳細について語ります。Wiki 上でのテクニカル ドキュメントの作成、公開、構造化および管理に関する弊社の体験談をお話しますので、乞うご期待ください。

  前の記事 次の記事  

関連記事