ドキュメントの重要性について

私たちの多くは、アプリケーションソフトウェアの開発プロセスがすでに確立されている企業で働いており、さまざまなドキュメントがこれらのプロセスの不可欠な部分です。 ただし、技術文書を記述するための伝統やプロセスがなく、すべての情報が人々の頭の中や企業の電子メールにある企業があります。 最初のタイプの会社から2番目のタイプの会社に来た場合、作業文書が空気のように必要であることがすぐにわかります。 なんで？ ソフトウェア開発の主な種類の作業文書を見て、それらのない生活を想像してみましょう。



1.参照条件。 TKは、ビジネスと開発の間のリンクです。 これは、ビジネスとプログラマーが何をどのように実装すべきかについて共通の意見を持つ文書です。 会社がTKを作成することが慣習的でない場合、誰が既に実装されているものとまだ実装されていないものを理解することはできません。 これは、時間が経つにつれて人々が変化し、管理部門が変化し、機能が1つのユニットから別のユニットに移動するなど、機能の繰り返しの重複を避けられません。 さらに、既に実装されている機能を新しい機能で補完することは非常に困難になります。何がどのように実装されたのか（特に新入社員）を理解するためには、何十人もの従業員と話し合い、数ヶ月間の企業通信を上げる必要があるためです。



2. HLA（高レベルアーキテクチャ）。 このドキュメントでは、ToRに記述されているものを実装する方法をアーキテクチャレベルで説明します。 変更を行う必要がある場所、変更の本質について説明し、このドキュメントでは、モジュール/サブシステム間のインターフェイスなどの非常に重要な部分について説明します。 誤解しない限り、DeMarcoとListerは、システムとインターフェイスの相互作用中に最も「悪い」バグ（つまり、発見と除去が困難）が発生することを非常に正確に指摘しました。 HLAは開発チームと一貫しているため、実際、このドキュメントは、開発チームが製品の相互作用について合意する1つの場所です。 これらのドキュメントを書かないと、インターフェイスを不適切に実装した人を見つけることができなくなり、最終的には間違いなくアーキテクチャのエラーにつながり、将来的には非常にコストがかかる可能性があります。 コードの品質は劇的に低下し、ローカライズが困難なエラーが多く発生します。 さらに、将来的には、2つのモジュール間の相互作用がどのように機能するかを理解するために、新しい人は再び何十人もの人々とコミュニケーションを取り、数か月間の通信を増やす必要があります。



3. LLD（低レベル分解）。 これは、開発チーム内で作成されたドキュメントです。 実装に必要なすべてのメソッドとAPIを詳細に説明します。 実際、このドキュメントを書いた後は、記述されたものをエンコードするだけです。 このドキュメントがないと、プログラマは何をする必要があるかを明確に理解できず、将来的にはバグの数が増えます（つまり、コードの品質が低下します）。



4. PMI（プログラムおよびテスト手順）。 これはおそらく、テスト分野の主要文書であり、実装された機能が正しく機能し、ToRに従って動作することをビジネスが明確に判断するために何をする必要があるかを段階的に説明しています。 そのような文書がないと、機能のエラーをチェックできません（TKの不一致もバグです）。これにより、最終的には、機能の完全な動作不能まで、多数のバグが本番プラットフォームで発生するリスクが大幅に増加します。 さらに、このドキュメントがなければ、ビジネスによる機能の受け入れは、ビジネスによる開発に対する根拠のない主張など、すべての結果を伴う非公式のプロセスに変わります。



5.ユーザーマニュアル。 ソフトウェアを使用して特定のビジネスプロセスを実行するためにユーザーが行う必要があること。 多くのスクリーンショット、わずかな言葉。 このドキュメントがなければ、ユーザーはくしゃみごとにサポートと（特に高度なケースでは）開発を定期的に呼び出します。 言うまでもなく、このドキュメントを持たない新入社員にとって、エンタープライズアプリケーションソフトウェアを理解することは非常に難しいでしょう。エンタープライズアプリケーションソフトウェアは、通常、軽さと直感的なインターフェイスで区別されませんか？



6.システム管理者ガイド。 アプリケーションソフトウェアに必要なリソース、このソフトウェアの構成方法、および特権と権利の配布方法を説明する非常に必要なドキュメント。 このドキュメントは、システム管理者とテクニカルサポートの両方で使用されます（これはどこでも同じユニットではありません）。 このドキュメントがないと、ソフトウェアは最も重要な瞬間にリソース（CPUコア、ディスク容量）がなくなるリスクを負います。 また、権利のタイムリーな配布には多くの問題があります。2人が頭の中に情報を持っている場合、1人は病気で、もう1人は休暇中です。 1週間はビジネスにとって非常に長い時間です。 ビジネスでは、1時間でも長すぎます。



この記事では、何かの必要性の出現から生産におけるこの何かの実装まで、開発プロセスに付随するすべての文書とは程遠いことを明確にしています。 プロジェクト管理の分野にはまったく触れませんでした。この分野では、ドキュメントが基本の基礎となります。 すべての開発およびテストドキュメントについては説明しませんでした。 しかし、私はあなたを納得させたことを願っています（本当にこれを納得する必要がある人はいますか？）その技術文書は非常に必要かつ有用なものであり、ソフトウェアを開発するときに決して無視されるべきではありません。



文書を書いてください！