技術的な（将来の開発者向けの）ドキュメントはどれくらいですか？適切なコーディング時間と文書化時間の比率はありますか？
最も理解しやすくするために必要な最小限のドキュメントを作成し、
それは良いガイドラインですか、それとも私が作成すべき具体的なものはありますか？
回答:
ラ・パーフェクション・エスト・アテインテ・ノン・パス・アンド・ア・リエン・ア・ジューター、メイン・アンド・ア・イン・ア・リエン・ア・リタイア。
アントワーヌ・ド・サン=テグジュペリ
私はしばらくこのトピックについて考えていました。
私の結論は-それは量の問題ではなく、質と文脈の問題です。
たとえば、適切なプロジェクト構造は、ファイルの場所を説明するコメントよりも優れています（実装vs意図）
同様に、コンテキストを明確にするための分類はネーミングよりも優れています（患者のID-> Patient.Id）。
DDDは優れたドキュメントに発言権を持っていると思います-分類はコンテキストを提供し、コンテキストは境界を作成し、境界は意図的な実装につながります（これは存在する必要があるのではなく、これが属する場所です）。
コード自体は、ドキュメントと見なされるほど十分ではありません。ほとんどの場合の問題は、コードの動作がコメントされているかコメントされていないという事実にあるのではなく、原動力（ドメインロジック）にコメントがないという事実にあります。
誰がボスであるかを忘れることがあります-コードが変更されても、ドメインロジックまたは推論は変更されるべきではありませんが、ドメインロジックまたは推論が変更されると、コードは間違いなく変更されます。
一貫性も非常に重要です-一貫性がなければ、それ自体の慣習は役に立たない。
設計パターンは単なる「良い習慣」ではありません-開発者が理解すべき専門用語です。開発者にファクトリに新しい型を追加するように指示する方が、新しい型をメソッドに追加するよりもよく理解できます（コンテキストと一貫性が弱いか欠落している場合）。
闘争の半分は親しみです。
補足として、多くのドキュメントを支持していると思われるAPIも、ドメインとコンテキストに非常に敏感です。機能を複製することは悪ではなく（同じこと、異なるコンテキスト）、時には別個のものとして扱われるべきです。
コメントに関しては、推論の背後にあるドメインロジックを指摘することは常に良いことです。
たとえば、あなたは医療業界で働いています。メソッドでは、「IsPatientSecure = true;」と記述します。
これで、まともなプログラマーは、患者が安全であるとマークされていることを理解できます。しかし、なぜ？その意味は何ですか？
この場合、患者は施設外の病院に安全に移送された受刑者です。これを知っていれば、この時点に至るまでの出来事（そしておそらくまだ何が起こる必要があるか）を想像するのは簡単です。
たぶん、この投稿はせいぜい哲学的なように見えるかもしれません-しかし、それはあなたが書いているのはコードではなく、「推論」または「論理」であることを忘れないでください。
Papadimouslisの引用に同意します。ソースコードはそれ自身で話すことができますが、コードはそれが存在する理由、それがどのように使われるべきか、そしてコードがどのように振る舞うべきかをあなたに伝えることができません。
私は良い比率を知りません。
私は非常に少ないドキュメントで何百行ものコードを継承しました。コードが書かれた理由を理解するのが難しくなりました。コードが書かれた理由を見つけた後、コードの使用方法を理解する必要がありました。それを見つけた後、コードをサポートおよび保守できるように、どのように動作するかを理解する必要がありました。
経験から、コメントを具体的にしすぎないようにしてください。さもないと、実際のコードとドキュメントを維持しなければならなくなります。ドキュメントとコードが同期していない場合、悪夢です。
2番目の推測をやめるのに十分です。
作業中にいつでも「うーん、これを文書化する必要がある」と思ったら、先に進んでください。次に、いくつかのドキュメントを作成していて、「これをもっと説明する必要があるかもしれない」と思ったら、先に進んでください。
その感覚がなくなるまで、繰り返しすすいでください。
George Fairbanksの著書Just Enough Software Architectureに示されているようなリスク駆動型のアプローチは、ドキュメントがどれだけあれば十分かを理解するのに非常にうまく機能することがわかりました。彼のウェブサイトでこの概念を提示するセクション（第3章）を読むことができますが、主なアイデアは次のとおりです。
リスクを優先できるように懸念を調整するために、成功のしきい値として知られるいくつかの目標を特定することが役立つことがわかりましたは、「成功、つまりチームが「成功」プロジェクトが達成しなければならないと考える目標の最小セット。ドキュメントの観点から、ToSの例は、「開発者がフレームワークを初めて選択してから4時間以内に簡単なプラグインを構築できるはずです」のようなものです。
次に、いくつかのリスクを特定します。構築した（または構築中の）システムで、チームにとって最も心配なことは何ですか？これらをリスクステートメントとしてフレーズします。SEIの条件と結果のスタイルが好きですが、他にもあります。例：
チームとして、リスクに優先順位を付けます。マルチ投票は非常にうまく機能します。
最優先のリスクを軽減し、プロジェクトの失敗のリスク（成功のしきい値で定義）が許容範囲内になるまで、識別から始めます。一般的に、これは、チームがそれほど心配しないことに同意するリスクがあることを意味します。おそらく、すべてのリスクを軽減したくないことを覚えておいてください。上記の最後のリスクに対する緩和戦略の例は、チュートリアルを作成することです。
できるだけ少ないが、必要なだけ
最初に聞いた場所と時期を思い出せませんが、多くのアプリケーションでそれは格言です。
テクノロジーやアプリケーションが複雑であればあるほど、より多くのドキュメントが必要になることは明らかですが、明らかに時間を無駄に使いたくないのは明らかです。
JohnFxの「廊下テスト」は健全です。しかし、自分を信頼してください。コードを開発したので、すべての人が、特別な注意を必要とする要素、およびすべての人にとって明白な要素について感じているはずです。コードの開発に苦労したことを考えてみてください。他の開発者がコードを見たときに、他の開発者が何を目にするかがわかるでしょう。
コーディングに費やした労力と文書化に費やした労力の関係を忘れてください。
これを正確なルールに入れることはできないと思います。文書化の理由は、他の人が生のコードを理解し、おそらく維持するために、生のコードから簡単に収集されない知識をフォームに提供することです。
したがって、十分に文書化したかどうかを判断できる唯一の方法は、対象の視聴者に十分かどうかを尋ねることです。「ピアレビュー」プロセスは、これを事前に行うのに非常に優れていると思います。ピアがあなたの話していることを理解し、それを最小化するためにどれだけの説明が必要であるかに注意してください。
これを一度も実行したことがない場合、どれだけの作業が必要かを見積もることはできませんが、数回の反復を行うと、どれだけの作業が必要であるかがよりよくわかります。