ドキュメントはどのくらい重要ですか？
ドキュメントはどれほど重要ですか？またはその問題の仕様は？
私は約5年間、専門的にソフトウェアを書いています。仕事を始めるたびに、コードを読んですべてがどのように機能するかを理解し、メモを取り、最終的には最初に持っていてほしいドキュメントを作成することに数日費やすことに直面することがよくあります。
これらの企業のいくつかは非常によく知られており、十分なドキュメントがないことに驚いています。
これは他の誰もが知っているものですか？
ドキュメントは重要であることに誰もが同意します。
しかしながら...
多くのプログラマーはコードは「自己記述的」である必要があります）コード自体がドキュメントとして機能する必要があるため、ドキュメントは不要であると信じています。しかし、それはある程度まで当てはまります。コードはコンポーネント間の関係を適切に文書化していません。プログラマーに100,000行のコードベースを調べて何を理解するよう依頼するのは無理ですあなたが書いたこれらすべての抽象ファクトリファクトリファクトリオブジェクトは、実行することになっています。
ドキュメント化には時間がかかります。ほとんどの企業の最優先事項は、ドキュメントではなく出荷です。ドキュメントがある場合、多くの場合、ビジネスプロセスをドキュメント化するか、ユーザーガイドを提供しますが、ソフトウェアコンポーネント間の関係は提供しません。
ドキュメントは維持する必要のある別のことです自己文書化コードとは異なり、ドキュメントは最新の状態に保つ必要があります。
これらすべての理由により、ドキュメントはしばしば無視されます。
最新の正しいand適切に設計されたドキュメントは必須です。ただし、これらの3つの基準を満たさない場合は、役に立たないというよりは悪いことです。
私が中規模/大規模プロジェクトで見つける問題の1つは、ドキュメントについてのフェティッシュがあることですが、ドキュメントの目的の概念はまったくありません。
- ドキュメントはnotチェックボックスです。
- ドキュメントはnotインストール/構成ウィザードのボイラープレートスクリーンショットを主に含むMicrosoft Wordの「ドキュメント」です。 （私が見つけた（または私から要求された） "ドキュメント"の99％はこの種のものです）。
- ドキュメントは注釈付きライブグラフall関係（システム内フローと外部フローの両方）です。
- ドキュメンテーションはライブウィキall ITの利害関係者が共同で作成したものです。プロジェクトとは言っていないことに注意してください。
- ドキュメントにはall構成オプションを含める必要があり、それぞれにどの値あるか正確に指定する必要があります場所と方法その値は獲得しました。
- ドキュメントにはwhyオプションXの値がYであり、決定がtechnicalであったかどうか（たとえば、ジャンボフレームを使用していること）も記載する必要がありますパフォーマンスが向上し、システム負荷が軽減されるため）またはpolitical（たとえば、20年前にいくつかの悪い経験があったため、オートネゴシエーションを使用していません以前のバージョン0.0.1カード/スイッチ）。
可能な限り「ドキュメント」を使用しないでください。グラフを作成し、wikiに文書化して、CMDBからデータをロードします。
重要なのは、このドキュメントは、何年にもわたって作業してきた人たちよりも、あなた（新しい人）にとってはるかに有用です。私は同様のドキュメントを作成し、しばらくの間それらを維持しました。しかし、誰かが私から拾い上げようとした場合、彼らは困難に直面すると思います。