Wiki でドキュメント作成の負担を軽減 - TechRepublic

厳密に管理された開発部門であっても、特に実装フェーズではドキュメントの維持管理が困難な場合があります。ドキュメントが必要になったとしても、後回しにされることがしばしばあります。また、ドキュメントの転記となると、正確性が損なわれる可能性があります。

正式なドキュメント作成プロセスでよくある問題を避け、タイムリーで簡単にアクセスできるドキュメントを作成するにはどうすればよいでしょうか。WikiWikiWeb、略して Wiki をインストールしてください。

WikiWikiって何？
「Wiki Wiki」はハワイ語で「速い」という意味で、まさにぴったりの名前です。Wikiとは、共同編集が可能なウェブサイトで、データの蓄積と精緻化を最小限の手間で促進するように設計されています。Wikiを閲覧しているユーザーは誰でも、表示されている内容を迅速かつ簡単に編集できます。Wikiの使い方は、リンクされたワードプロセッサのページをまとめて閲覧するようなものです。Wikiに貢献するために、HTMLなどのマークアップ言語の知識は必要ありません。

最初のWikiはPortland Pattern Repositoryにありました。現在も活発に利用されており、Wiki Wiki Web FAQページを含む2万以上のWikiページがあります。この最初の例から、数千ものWikiが作成されました。数十ものソフトウェアパッケージがWiki機能を提供しています。Wikiは、誰でもアクセスできるようにすることも、社内でのみアクセスできるようにすることもできます。

Wikiのインストール
Wikiでドキュメントを作成する前に、まずWikiをインストールする必要があります。Webで簡単に検索すれば、様々なWikiソフトウェアが見つかります。どれも基本的な機能は同じですが、開発言語、WebサーバーとOSの要件、そして提供される補助機能がそれぞれ異なります。

利用可能なWikiソフトウェアパッケージを数多く試してみましたが、MoinMoinWikiという無料のものが一番気に入っています。MoinMoinは、使いやすさ、インストールの容易さ、そしてパワーのバランスが絶妙です。Windows、Linux、Mac OSXのサーバープラットフォームにも対応しています。

MoinMoinソフトウェアをダウンロードしたら、簡単なインストール手順に従ってください。あっという間にあなただけのWikiが完成します。

Wikiの使い方
Wikiをインストールしたら、Webブラウザでアクセスしてトップページを見てみましょう（  図A参照）。Wikiの使い方に関する一般的な説明が記載されていますが、実際に読む人はほとんどいないでしょう。この地味なトップページは、お好みに合わせて簡単にカスタマイズできます。

図A

ウィキのトップページ

ページ下部の「テキスト編集」リンクをクリックします。ブラウザに、  図Bに示すように、先ほど表示したページの全文を含む大きなテキストエリアが表示されます。この時点では2つの選択肢があります。同僚が実際に読むテキストを既存のテキストの上に挿入するか、既存のテキストを完全に置き換えるかです。

図B

Wikiページの編集

現時点では、どのようなテキストを追加するかはそれほど重要ではありません。Wikiページはすべて何度も改訂されますが、フロントページほど頻繁に改訂されるものはありません。私は通常、新しいWikiを作成する際には、簡潔な導入文と、初めてWikiを使用するユーザーがすぐに入力できるページへのリンクをいくつか追加します。この記事の後半でいくつか例を挙げます。

当然ながら、「Wikiページにリンクを追加するにはどうすればいいのでしょうか？」という疑問が湧きます。手順は非常に簡単です。Wikiページにリンクを作成するには、大文字の単語を2つ、スペースを入れずに並べるだけです。例えば、この文では「WikiWord」という文字列がリンクになります。これは「WikiWord」という名前のWikiページへのリンクです。Wikiを閲覧中にユーザーが「WikiWord」リンクをクリックすると、WikiWordページが存在する場合はそのページに移動し、そうでない場合は新しいWikiWordページを作成するかどうかを尋ねられます。

このシンプルなリンク構文と、まだ存在しないページにリンクしても見苦しい404エラーが出ない機能を組み合わせることで、Wikiの有機的な成長を容易に実現できます。例えば、Linuxに関するページを書いているときに、LinusTorvaldsという単語を意図的にスペースなしでリンクとして挿入したとします。ただし、LinusTorvaldsページを作成する意図は全くありません。後になって、誰かがそのLinuxページを読んでTorvalds氏について少しは知っていると思ったら、リンクをクリックしてページの作成を選択し、そのトピックに関する短い文章を書き加えることができます。すると、そのページには、後で作成される他の存在しないWikiページへのリンクが含まれる可能性があります。

Wiki を売り込む Wiki
を作成したら、ドキュメント作成作業を Wiki に移すのにほとんど労力がかからないことに気付くでしょう。必要なのは、将来 Wiki に移行したユーザーが興味を持ちそうなコンテンツを少し作成することだけです。最初に行うべき場所はフロント ページです。私は通常、フロント ページの組み込みコンテンツのほとんどを削除し、CompanyEmployees、DocumentationLinks、ExternalResources、FunnyStuff などのリンクに置き換えます。次に、リンクをクリックし、要求されたら新しいページの作成に同意することで、これらのページを作成します。CompanyEmployees ページには、プロジェクトの各開発者へのリンクを配置します。名前は Wiki のリンクとして最適で、自分のリンク切れの名前をクリックして個人の Wiki ページを作成しない開発者はほとんどいません。

その他のページには、Wikiソフトウェアが表示時にクリック可能なリンクに変換するシンプルなURLを含めることができます。プロジェクト開発者が頻繁に参照する社内外のドキュメントへのリンクをすべて集めることで、便利な共有ブックマークページが実現します。これだけで、他のユーザーをWikiに引き込むのに十分な場合が多いでしょう。

Wikiライフを満喫する
Wikiにコンテンツを追加したら、プロジェクトのリソースや豆知識を見つけられる場所として、Wikiを積極的に宣伝しましょう。たとえリクエスト者が情報を探す前に、急いで入力しなければならない場合でも、できるだけ多くの情報リクエストに「Wikiにあります」と答えましょう。

Wikiは、独自のドキュメントに収まりきらないようなちょっとした知識を保存するのに最適な場所です。開発アカウント情報、締め切りリスト、その他様々なヒントやコツなどは、Wikiの優れた素材になります。プロジェクトメンバーが貴重な情報を探す際に、すぐにWikiが最初の参照先になることに気づくでしょう。