このブログ記事は、TechRepublic ダウンロード ライブラリから PDF としても入手できます。
正直に言うと、誰もそれについて書きたいわけでも、読みたいわけでも、実際にやらなければならないわけでもありません。ここで私が言っているのは、ドキュメント作成です。これは通常、プロジェクトライフサイクルの最後から2番目のステップと定義されます。ドキュメント作成はプロジェクトライフサイクルのどの段階でも行うべきであり、また行うべきでもありますが、この記事ではドキュメント作成フェーズに焦点を当ててヒントを解説します。なお、ここで説明するドキュメントには、エンドユーザー向けドキュメントとシステム/社内向けドキュメントの2つのサブセットがあります。
プロジェクトライフサイクル
この記事の調査中に、アンソニー・ラルストンとチェスター・L・ミーク編著『 Encyclopedia of Computer Science』（Petrocelli/Charter、1976年）を取り出しました。確かに初版の古典ですが、時代を超えて残るものもあります。資料一覧には次のように記されています。
「コンピュータベースのシステムの開発と利用において、ドキュメント作成は極めて重要です。一部の商業組織では、開発総労力の20～40%が新システムのドキュメント作成に費やされ、新システムの動作方法と開発過程が記録されています。」著者、KRロンドン
それが今日でも当てはまるのかどうか、そしてもし当てはまるなら、なぜドキュメント作成はメディアで十分に取り上げられないのか、興味がありました。プロジェクトライフサイクルにおけるドキュメント作成のコストに関する情報はあまり見つかりませんでした（図A参照）。これらのコストは過小評価されているか、適切に徴収されていないことが多いのではないかと考えています。実用システムの開発を仕事とするITプロフェッショナルにとって、ドキュメント作成の実際のコストを認めることは恥ずかしいこと、あるいは生産性や仕事の質を落とすことになると考える人も多いでしょう。
プロジェクトライフサイクルにおけるドキュメント作成フェーズに対する考え方は、IT組織における役割によって異なるでしょう。マネージャーやプロジェクトリーダーにとって、ドキュメント作成はプロジェクトの成功に不可欠です。一方、非管理職にとって、ドキュメント作成は本来の業務の妨げとなる厄介な存在です。以下の10のヒントは主に後者を対象としていますが、マネージャーやスーパーバイザーにも役立つはずです。
図A
プロジェクトライフサイクルの7つのステップの出典: Wikipedia
1: 可能であれば写真付きで記録する
「一枚の写真は千の言葉に値する」という古い格言は、文章を補足するために写真を使うことで、ドキュメントの長さと複雑さを最小限に抑えられることを意味します。システムユーザーは、すぐに参照できるように、写真、図、表、箇条書きのリストを用意することを好みます。
#2: 例を挙げる
エンドユーザーが十分に理解していない概念を素早く理解するには、例を挙げることが重要です。また、新しいソフトウェアを学習しているエンドユーザーにとっても、新しい課題に取り組みやすくなるため、非常に役立ちます。以下に、画像付きのドキュメントの例を示します。
Vista Business、Ultimate、Enterprise の以前のバージョン
「以前のバージョン」とは、Microsoftがファイルのシャドウコピーを保存することを指す用語です。ドキュメントやその他の労力を要するプロジェクトで作業中に、誤って作業内容の一部または全部を失ってしまった場合でも、以前のバージョンに戻すことができます。これは、ファイルの過去の状態をスナップショットとして自動的に保存する手段と考えてください。
ただし、まず、以前のバージョンのファイルを復元する機能が必要な論理ドライブ/パーティションに対して、以前のバージョン (図 B ～ E) がオンになるように Vista を構成する必要があります。
以前のバージョンを有効にする
図B
スタート | コントロールパネルを選択
図C
「システムの詳細設定」を左クリックします — UAC (ユーザー アカウント制御) のプロンプトが表示されたら、「続行」を左クリックします
図D
システム保護タブを左クリックします
注意： Vista の論理ドライブ/パーティションはデフォルトで有効になっています。この設定を変更する場合は、変更に伴う影響を十分に理解している場合にのみ変更してください。
図E
下にスクロールして論理ドライブを確認します
スクロールバーを左クリックし、論理ドライブ/パーティションを下にスクロールして、以前のバージョンを有効にする論理ドライブ/パーティションを見つけます。この例では、その論理ドライブ名は「Documents」です。論理ドライブ名の横にあるチェックボックスを左クリックします。
注: シャドウコピーは、システムによって作成された復元ポイントの時間と頻度に基づいて作成されます。Vistaのヘルプファイルによると、通常は1日に1回です。
「適用」を左クリックし、「OK」を左クリックして「システムのプロパティ」ウィンドウを閉じます。「ファイル」→「閉じる」を左クリックするか、「コントロールパネル」→「システム」ウィンドウの右上にある赤い「X」ボックスを左クリックして閉じます。
ファイルの以前のバージョンを復元するには、エクスプローラーでファイル名を右クリックし、「以前のバージョンの復元」を左クリックします。
注意：ファイルのシャドウコピーを復元すると、2回目の復元には使用できなくなります。次のシステム復元ポイントが作成されるまで、新たなシャドウコピーは作成されません。つまり、次のシステム復元ポイントより前に保存されたファイルは、以前と同じバージョンに復元することはできません。「以前のバージョンを復元」オプションを使用した後は、次の復元ポイントが作成され、新たなシャドウコピーが作成されるまで、ファイルの保存には注意が必要です。
#3: 決めつけない
対象ユーザー層が明確であっても、ドキュメントは基本的なコンピュータスキルを持つ人でも読みやすく、システムの正しい使い方を習得できるように作成する必要があります。可能な限りステップバイステップの説明を提供する必要がありますが、煩雑にならないように、付録や別の章に配置するか、ハイパーリンクでアクセスできるようにすることを検討してください。ドキュメントを作成する場合は、新しいシステムユーザーの立場に立って考えるように意識を変えてください。最初は難しいかもしれませんが、細部に注意を払い、すべての機能を完全にドキュメント化することで、記載漏れした情報や手順をユーザーが理解できると想定しないドキュメントを作成できます。
IT業界に溢れる頭字語をエンドユーザーが全て理解しているとは考えないでください。新しい頭字語を初めて提示するときは、その頭字語が何を意味するのかを詳しく説明してください。
＃4：問題を予測する
システムをテストする際には、あらゆる手段を尽くしてソフトウェアを壊すように努めるべきです。ソフトウェアに既知の問題（開発者はこれを「問題」と呼び、エンドユーザーは「バグ」と呼びます）がある場合は、回避策を文書化し、ユーザーとヘルプデスクに提供してください。エンドユーザーのフラストレーションを大幅に軽減できるだけでなく、ヘルプデスクへの問い合わせも大幅に削減できます。
長期にわたって使用されるシステムの存続期間中に避けられないイベントを文書化します。
- システムまたはネットワークがダウンしている間、どのような回避策を利用できますか?
- サーバーの停止、ハードディスクのクラッシュ、データベースの破損からどのように回復しますか?
- システムについて全く何も知らない人が、どうやってシステムを再び稼働させるのでしょうか?
ドキュメントではこれらの問題を予測し、システム回復のための詳細な計画と手順を提供する必要があります。
後任者は、あなたのドキュメントや購入したベンダーアプリケーションドキュメントがどこにあるか知っていますか？これらのドキュメントはすべて、きちんと整理され、安全で分かりやすい場所にまとめて保管されている必要があります。
問題を予測する良い例として、Y2Kミレニアムバグ問題とその解決策が挙げられます。1990年代後半、レガシーシステムでは年を2桁しか保存できないため、システムやソフトウェアに障害が発生する可能性が高いとメディアが報道し始めました。この問題は事前に予測されており、発生前に多くの労力が費やされました。開発中のソフトウェアは、2000年1月1日の何年も前にY2K対応として構築・認定されました。その結果は驚くほど成功を収めました。いくつかの軽微な問題が報告されたことを除けば、2000年の元旦はITコミュニティにとって大きな痛手ではなく、祝祭的な出来事でした。ただし、万が一に備えて多くのスタッフが待機していました。
同様の考え方は、ドキュメント作成において発生する可能性のある問題を予測する際にも活用できます。2000年問題は、ドキュメントの継続的な更新の必要性を浮き彫りにしました。システム／内部ドキュメントは、ソフトウェアおよびシステムの2000年問題への対応状況または非対応状況を記載するように変更されました。古いレガシーシステムについては、回避策が見つかり、文書化されました。
#5: ドキュメントをテストする
落ち着いて、自分の指示に従ってください。サーバー、ネットワーク、その他のITシステムの構築を文書化する場合は、まずまっさらなパーティションから始めて、すべてをゼロから構築してください。きっと、何かが抜けていたり、指示が不明確だったりすることに気づくでしょう。
公開前に、知識は浅いものの熱意のある同僚と協力してフィードバックをもらいましょう。彼らにドキュメントをテストしてもらいましょう。
初めて誰かにソフトウェアとドキュメントを使ってもらう時、その学びにきっと驚くでしょう。あなたにとっては当たり前のソフトウェアの機能も、誠実で協力的な人にはあまり理解できないかもしれません。モルモットがソフトウェアを操作している様子を注意深く観察し、フィードバックを求め、メモを取りましょう。
あるプロジェクトのテスト中に受け取ったフィードバックを覚えています。フィードバックはメールで送られてきたので、一つ一つ確認することができました。最初に頭に浮かんだのは「これにはどれくらい時間がかかるだろう？」でした。これらのコメントを批判的、あるいは個人的なものだと捉えてしまうこともあるでしょう。しかし、そのような間違いはしないでください。今振り返ってみると、親切な批評家が提供してくれた不足機能をもっと実装すべきでした。
この機会を利用して、プロジェクトの最終的な調整を行ってください。ドキュメント作成プロセス中のフィードバックは、プロジェクト全体の成功につながります。
Foxconn 975X7AB-8EKRS2Hマザーボードのレビューを書いていたのですが、マニュアルに2つの誤りを見つけました。このマザーボードをレビューしたのは私が初めてではありませんでした。Foxconnはこれらの誤りを見逃しており、他のレビュー担当者も同様に見逃していました。マニュアルの1つの誤りは、決して軽微なものではありませんでした。
マニュアルに記載されていたCMOSクリアジャンパーの標準位置を示す図が間違っていました。ヒートシンクが正しく取り付けられているかどうかを確認するためにマザーボードを裏返した際に、ジャンパーが外れてしまったため、このエラーに気づきました。マニュアルの指示に従ってジャンパーを元に戻したところ、コンピューターはPOSTに失敗しました。マザーボード上の小さな図をよく確認した後、エラーを発見し、ジャンパーの位置を修正しました。
当時、Foxconnの技術者と一緒に仕事をしていたのですが、彼は親切にも私の質問に答えてくれたので、このエラーについて伝えました。このようなドキュメントの誤りは見落とされやすく、メーカーに多大な損害をもたらす可能性があります。ジャンパーが緩んでいて、マザーボードを裏返した際に外れてしまったため、私自身もこのエラーに気づかなかったでしょう。
#6: 仕事に人間味を与える
ユーザーマニュアルを読んでいて、そのマニュアルの作成に本当に人間が関わっていたのだろうか、それともコンピューターが作ったのだろうかと疑問に思ったことは、何度ありますか？ 華やかな小説を作る必要はありませんが、読者が少しでも心地よく読めるように、あなたの個性を少しだけ表現して、ドキュメントに人間味を加えましょう。
#7: 新しいテクノロジーを探る
ドキュメント作成は、適切に実施してもコストがかかる場合があります。より効果的で開発コストの低いドキュメント作成を支援する新しいテクノロジーは今後も開発され続けるでしょう。これらの新しいツールを、ドキュメント作成プロセスの時間とコストを削減する機会と捉えましょう。
プロジェクトチームの一員としてドキュメントを作成するのは、特に困難を伴う場合があります。作成したドキュメントは他のチームメンバーのドキュメントと共有し、追加していく必要があります。変更は、多くの場合毎日行う必要があります。これを可能にするソフトウェアがあり、最終製品の標準化を実現するだけでなく、チームメンバー間でのアイデアや知識の共有を促進するのにも役立ちます。
CSC（コンピュータサイエンス・コーポレーション）で働いていた頃、マイクロソフトのエージェントと音声合成技術を試したことがありましたが、結果はまちまちでした。新しいユーザーにシステムの機能を案内する上で、これらの技術は素晴らしいものだと常々思っていました。Word 97で、目が点滅する小さなクリップのキャラクターが目障りだったことを覚えている方もいるかもしれません。あれは、ただでさえ迷惑なものでした。
Agentを使えば、キャラクターを画面上を移動させたり、ドロップダウンボックスをポイントさせたり、プログラムでドロップダウンボックスを開いたり、表示された選択肢についてキャラクターが話しかけたりすることができます。私はソフトウェアのガイドツアーを作成し、オウムのPeedyにボックスをポイントさせたり、テキストボックスに入力させたり、画面を切り替えさせたり、データベースに新しいレコードを作成するプロセス全体をエンドユーザーに案内させました。
Agent を使うことで、新しいレコードの作成、保存、変更に必要な手順を詳細に記述した、何ページにも及ぶ退屈なドキュメントを作成する必要がなくなりました。開発自体も楽しく、私の創造性をポジティブかつ有益な形で発揮することができました。創造性はほとんどの開発者に備わっており、成功の鍵となる要素です。会社の基準や期待に応じて、ドキュメントを作成する際に創造性を考慮することは可能ですし、考慮すべきです。
MSエージェントの実験について私が受け取った唯一のフィードバックは、誰かが暇を持て余していて、真剣に受け止めてもらえなかったというものでした。少なくとも、そのコミカルなキャラクターのせいで、真剣に受け止めてもらえなかった部分もありました。構築にそれほど手間はかかりませんでしたが、新しいコーディング技術を学ぶ必要がありました。部署の誰かがトレーニングを受けることになったときは、本当に嬉しかったです。ガイドツアーに参加するように勧めました。もしかしたら、マイクロソフトは時代を先取りしていたのかもしれません。もっとまともなキャラクターがいれば、この種の技術もいつか主流になるかもしれません。
最近、父の結婚50周年記念のプレゼントとしてパソコンを組み立てました。「重要なPCメモ 必ずお読みください」と記したメモをいくつか書き、デスクトップにショートカットを残しました。また、パソコンの機能と使い方を記録した音声ファイルも作成しました。父にメモを見たかどうか尋ねてみたのですが、ケースとパソコンの音声ガイドツアーに参加したと言ってくれました。
これらは、文書化の代替手段のほんの一例です。筆者としては、新しい文書化手段は、そのシンプルさと今日の企業環境における潜在的な影響力の割に、十分に活用されておらず、過小評価されていると考えています。
究極のドキュメント作成ソフトウェア パッケージはまだ開発されていませんが、特定のドキュメント作成タスク向けに設計された便利なドキュメント作成ツールは数多くあります。
#8: 可能であれば自分でドキュメントを作成する
文書化に最適なのはシステム構築者です。結局のところ、システム構築者以上にシステムを熟知している人はいないのではないでしょうか。
システムビルダーなら、おそらく腕利きのプログラマーでしょう。しかし、プログラマーにWord文書について話すと、「冗談でしょ」という顔をされます。プログラマーは、強制されれば、自分の作業を文書化するか、少なくとも文書として通用するものを作成しようとします。私もよく知っています。私は何度もそれを見てきましたし、私自身もそうしたことがあります。
これは本当に残念なことです。優れたドキュメンテーションスキルを持つプログラマーは会社にとって貴重な資産だからです。もしあなたのプロジェクトのドキュメンテーションを他の人が作成しなければならなかったら、上司は業績評価の際に何を覚えているでしょうか？おそらく、昇進や昇給、ボーナスに値するとは思わないでしょう。
ドキュメント作成は必ずしも楽しい作業ではありませんが、適切に行えば大きな成果が得られます。顧客に提示するプロジェクト全体の質が向上するだけでなく、将来のサポート時間も大幅に短縮されます。ヘルプデスクのサポートとメンテナンスにかかる時間も削減できます。
CSCで働いていた頃、グローバルなレポートシステムとインフラストラクチャの設計・構築のプロジェクトリーダーを務める機会に恵まれました。そこで、ドキュメント作成の裏側を目の当たりにすることができました。グループには、Crystal Reports APIの作業とカスタム関数の構築を担当する優秀なプログラマーがいました。彼の知識は彼独自のものであり、チームメンバーと共有する必要があることは明らかでした。そのためには、彼の作業をきちんと文書化することが最も効果的だと考えました。しかし、他の人が代わりに引き継げるほど、彼に作業を説明してもらうことはなかなかできませんでした。彼は関数名、使い方、動作、そして成果物を列挙して説明してくれました。これはチームの他のメンバーにとって非常に役立ちました。
コードの領域では、プログラミング スキルはプログラマーが作成しなければならないドキュメントの量に反比例するという暗黙のルールがあるようです。
これまでのキャリアで二番目に嬉しかった褒め言葉は、グローバルテクニカルサポートチームにプレゼンテーションをしなければならなかった時のことです。レポートサーバーの構築方法に関するドキュメントを作成し、発表する必要がありました。データベース管理者の一人であるイギリス出身の男性が、プレゼンテーションに同席することになりました。彼は「レポートサーバーの構築方法」のドキュメントを見て、簡単に言うと、このドキュメントの素晴らしさに感銘を受け、私のドキュメントを使って自分もレポートサーバーを構築できるだろうとコメントしてくれました。このような言葉を聞くと、これまでの苦労が報われるような気がします。しかも、これはプロジェクト全体の成果に対する褒め言葉ではなく、ドキュメントに対する褒め言葉だったのです。
#9: エンドユーザー向けドキュメントの開発と社内/システム向けドキュメントの開発を調整する
システムドキュメントの作成と同時にユーザードキュメントを作成すれば、ドキュメント作成時間を短縮できます。両者で情報を共有することで、情報不足を削減できます。たとえ情報を共有したくない、あるいは共有することが適切でない場合でも、一方のドキュメントで取り上げたトピックが、もう一方のドキュメントに追加ドキュメントを追加するきっかけとなることがあります。
＃10：部門または企業の文書化ガイドラインに従う
標準的なフォーマットとガイドラインを作成し、それに従ってください。これにより、重要な情報が漏れることがなくなり、システムユーザーが読みやすくなります。
ヒューズ・エアクラフト社で、専任のドキュメンテーション専門家にシステムのドキュメント作成を依頼したのが一度だけです。結果は素晴らしかったです。フォーマットは部門標準で、私が行うよりも良い結果が得られました。しかし、この結果を得るには多くの時間と労力を要しました。ドキュメンテーション専門家は、私のベータ版システムと私にアクセスし、質問に答える必要がありました。これはコストが高く、すべての企業が専門的なドキュメント作成にリソースを割けるわけではありませんが、システムビルダーが重要な情報が誤解されたり、最終製品から漏れたりしていないことを確認できれば、素晴らしい結果が得られます。
幸運なことに、ドキュメント作成にも優れた元エンジニアがいました。彼はシステムの設計目的と構築目的を理解しており、実際にシステムを使い、どのように動作するかを自ら体験することで、不明点を補ってくれました。あなたはそう簡単にはいかないかもしれません。
グローバルなマーケティング、販売、サポートが当たり前の現代において、ドキュメントも国や地域の標準に従うべきです。中国製の電子機器のマニュアルを読むと、翻訳が難しすぎてイライラすることがよくあります。中国語と英語の混ざった言葉で書かれていて、いくつかの文章は読み終えるまで読み進めなければなりません。たいていは心の中でスクービー・ドゥーの真似をして、マニュアルの残りの部分を読み進めます。
英語を話すドキュメンテーションのプロが（実際にはそうしませんが）中国語を学んで文章を書いたとしたら、中国語圏の人々にとって彼らの英語は同じように聞こえるでしょう。重要な情報が翻訳で失われないように、プロの翻訳者を見つけて活用し、ドキュメントを分かりやすくしましょう。
当然のことですが、文書にはスペルミスや文法上の誤りがあってはなりません。必ずスペルチェッカーを使って間違いを見つけてください。私自身、読み返した際に見落としてしまう明らかなスペルミスがいかに多いか、いつも驚かされます。
ドキュメント開発者
良質なドキュメントを作成することがあなたと雇用主にとって良いことだと、まだ納得していないなら、この事実に安心してください。良質なドキュメントを作成することは単なる単純な作業ではありません。自分の仕事をドキュメント化するということは、あなたもドキュメント開発者であるということです。これらのヒントが、あなたや親切なヘルプデスクの技術者に必ずやってくる、時間のかかる面倒な質問を避けるのに役立つことを願っています。
著者注:
これは私が公式に公開した初めての文書です。皆さんと私の考えを共有する機会を与えてくださったSonja Thompson氏とMark Kaelin氏に心から感謝申し上げます。Mark氏がなぜ私にドキュメンテーションという難題を最初の記事として取り上げる機会を与えてくださったのか、私にはよく分かりません。もしかしたら、ドキュメンテーションについて興味深い記事を書けるなら、ほとんど何でも書けるだろうと思われたのかもしれません。とはいえ、彼がそうしてくれたことは本当に嬉しく、彼とTechRepublicへの感謝は、この仕事の道具を使っても言い尽くせないほどです。
優しい読者は優しい作家になりました。
追加参考資料:
- 「…ドキュメンテーションに関する最も重要な4つの属性は、その内容、維持、可用性、そして例の使用です。」 http://www.site.uottawa.ca/~tcl/gradtheses/aforward/aforward_thesis.doc の58ページ
- ドキュメントの重要性: http://searchsmb.techtarget.com/originalContent/0,289142,sid44_gci1251087,00.html
