プログラマーはドキュメントの作成に注力すべきでしょうか？これは一見小さな問題ですが、比較的重要な問題です。ソフトウェアには、プログラムとデータのほかに、ドキュメントも含まれます。また、プログラマーがただプログラムを書けるだけで、ドキュメントの中で自分の考えを適切かつ優雅に記述できないなら、本当に「コードモンキー」になってしまいます。
ドキュメントを書く重要性
ソフトウェア関連の業界では、学校や職場で皆さんもすでに気づいているかもしれませんが、作成するプログラムや設計図を描くことのほかに、もう一つ重要な作業がドキュメントを書くことです。なぜドキュメントを書くのでしょうか？自分たちが作ったものを展示する必要があるからです。同業者に見せるだけでなく、他の職種のスタッフに見せることもあり、さらにはユーザーに見せることもあります。ただプログラムが書けるだけで、ドキュメントの中で自分の考えを適切かつ優雅に記述できないなら、それこそ本当に「コードモンキー」になってしまいます。
少し気づいたのですが、周りの同僚で高品質なドキュメントを書ける人は確かに非常に少ないです。李開復先生は『浪潮之巅』の序文で次のように述べています：「私は多くのトップエンジニアを知っていますが、強いストーリーテリング能力を備えた優秀なエンジニアは、私の知る限りごく稀です。」確かに、私が知る同僚の中でも、ドキュメントで自分の考えを明確に表現できる人はほとんどいません。
ドキュメント作成に関して、私が強く印象に残っている問題は以下のとおりです：
- 私たちは毎日たくさんのメールを送受信します。注意して見てみると、多くのメールの内容は、文が不自然だったり、誤字脱字が多かったり、句読点を誤用していたり、または句読点がなかったりします。多くの場合、異なる角度から理解すると、1通のメールは多くの異なる意味を持ち、結局何を伝えたいのか分からず、仕事の効率を大幅に低下させます。
- コードのほかに、プロジェクトには大量のドキュメントも含まれます。ほとんどのドキュメントを開いたとき、最初に私は次のような感覚を持ちます：レイアウトが整っていない、フォーマットが正しくない、文が通じない、誤字脱字だらけ。一目で著者が真剣にドキュメントを書いていないと分かり、しかも文の表現力や構成力も強くありません。
- プロジェクトチームのメンバーが議論するとき、皆ほとんどがどのように良いプログラムを書くかについて話しており、ドキュメント作成をどのように改善すべきかには触れません。開発者の役割は良いプログラムを書くことであり、他のことはすべて二の次だと、皆が一致しているようです。
コンピュータソフトウェアの伝統的な定義は次のとおりです：ソフトウェアはコンピュータシステムにおいてハードウェアと相互に依存するもう一方の部分であり、ソフトウェアはプログラム、データ、および関連ドキュメントの完全な集合を含みます。注意すべきは、ここで「関連ドキュメント」が言及されていることです。ドキュメントがきちんと書かれていなければ、ソフトウェアも優れたソフトウェアとは言えません。実際、ソフトウェアの機能は健全であるにもかかわらず、ドキュメントの問題によって障害が発生するケースはしばしばあります。
一般的に、ソフトウェア開発の過程では、異なる段階で関わる主要なドキュメントは次の図のとおりです：
このように、ソフトウェアの異なる段階では、異なるドキュメントを作成する必要があります。計画段階では、詳細設計書、単体テスト計画書、統合テスト計画書などを作成する必要があります。開発段階でもこれらのドキュメントですが、改訂版です。実際の開発中に、以前の設計で不合理な点や検討不足の点が見つかり、以前のドキュメントを修正する必要があるからです。テスト段階では、単体テストレポート、統合テストレポート、システムテストレポートなどを作成します。ソフトウェアのリリース段階では、インストールマニュアル、ユーザーマニュアル、アップグレードガイドなどを作成します。これらのドキュメントは主に現場サポートスタッフやユーザー向けであるため、できるだけ分かりやすく書き、曖昧な表現があってはなりません。そうでなければ、ユーザーからの苦情を待つしかなくなります。
良いドキュメントを書くためには、まず1つの認識を正す必要があります：「ドキュメントは重要ではない」という認識です。ドキュメントをプログラムと同じぐらい重要な位置に置く必要があります。
高品質なドキュメントを書くには？
では、どのようにすれば高品質なドキュメントを書けるのでしょうか？私は以下のいくつかの点から始められると思います：
- 「ドキュメントは補助」という考えを改め、普段の仕事で、自分が作成するすべてのドキュメントを真剣に扱います。
- メールの作成では、伝えたいことを正確に表現し、送信する前に、内容が完全かどうか、誤字脱字がないか、文が通じるかなどを再度確認します。
- ドキュメント作成の過程では、プロジェクトチームが規定したテンプレートを厳密に参照して作成します。ドキュメントを書き終えたら、文法チェックを行い、誤字脱字や文法的に誤った箇所を修正します。一般的に、文法的に誤りのある文の下には緑色の波線が表示されます。ドキュメントを提出する前に、もう一度ドキュメント全体を通読し、漏れや不足がないか確認します。
- 仕事の合間に、言語表現能力や文章作成能力を高めることができる書籍や記事を読み、他の人がどのように自分の考えを明確に説明しているかを参考にするとよいでしょう。例えば、CSDNの優秀なブロガーの記事を頻繁に読むことは、自分の文章力を高める良い方法です。
総じて言えば、他のことと同様に、ドキュメントを書くこともその人の態度を反映します。高品質なドキュメントを書くことは、個人のイメージを高めるだけでなく（良いドキュメントを読むと、著者に対しても高い評価を抱くのではありませんか？）、製品に対する顧客のイメージも高めることができます。このように考えると、ドキュメントを書くためにより多くの労力を費やすことは本当に必要です。
一つのことをうまく成し遂げるには、あらゆる面から努力する必要があります。ソフトウェア開発の過程では、良いコードを書くことも重要ですが、ドキュメントの中で自分の考えを明確に表現することも同様に非常に重要です。「コード」と「ドキュメント」は、人の両腕のようなものです。両方をバランスよく発展させなければならず、一方だけに気を取られてはいけません。
出典：CSDN著者：周兆熊