プロジェクトのドキュメントを維持するには？
プロジェクトのドキュメントを管理するが、ユーザー向けのドキュメントを管理するのではなく、メンテナのためのドキュメントを管理するのは実際にはどのように行われますか？たとえば、ファイルを見て、それがどのように機能するかを理解するのが慣習ですか、それともプロジェクトを説明するためにクラス図などが必要ですか？ Githubにクラス図があるプロジェクトはありません。
図ではなくコード上でプロジェクトの構造とクラスを直接推論することは悪い習慣ではありませんか？
これは完全な答えだとは思いませんが...
ドキュメンテーションは時代遅れになる傾向があります。開発者がコメントを更新するのを忘れたため、コード内のコメントが古くなった場合、別のファイルとして配置されたクラス図を想像してください。
あなたが見つける最良のドキュメントは、ソースコードからツールによって生成され、通常はコメントです。そして、はい、生成されたドキュメントの一部はクラス図の形式にすることができます。
Doxygen や Document！X や その他の選択肢 などのツールがあります。
そうは言っても、githubプロジェクトの大部分は1人または小さなグループによって保守されており、暇なときに無料で行われます...何かを機能させることを優先します...そこにドキュメントを作成する機会があるたびにまた、バグを修正したり、要求された機能を追加したりする機会にもなります。
そのため、中規模から大規模のプロジェクトに関する最高のドキュメントが見つかります。彼らは寄付や、開発者を雇うためのお金を得るビジネスモデルを持っています...そして、ドキュメントをセットアップしてそれを確認するのは誰かの仕事です完了し、最新の状態を保ちます。
ドキュメントが生成されていることを確認する責任がある人がいる場合、例があり、それらが機能する...そしてあなたは知っていますこの人がドキュメントを扱うのに忙しいにもかかわらず、開発は次第に進んでいきます（プロジェクトに関係する開発者がたくさんいるため）。それから、優れたドキュメントを持っている可能性が高くなります。
あるいは、プロジェクトに多くの人が関与している場合、コミュニティの取り組みとして、たとえばwikiの形式で行うことができます。
繰り返しになりますが、単一の開発者や小さなチームがそれを行うことができないということではありません。それが優先事項のように感じることは決してないので、彼らがそれをする可能性が低いというだけです。
さらに、それらはそれに対処する唯一のものです-繰り返しますが、通常は暇なときに-存在しない他のメンテナのためにドキュメントを書くよりも、きれいに読みやすいコードを持っている方がいいです...そしてはい、 （とりわけ）そのドキュメントがあると、より多くのメンテナを抱えやすくなる可能性があります。
ちなみに、クラス図のトピックについて...何かを計画している場合は、それをスケッチして、リポジトリに置く以外の方法で共有できます...（たとえば、共有かんばんボードに接続します） ）。システムを理解しようとしている場合は、コードからそれを生成するツールを実行できるため、リポジトリに置く必要もありません。
正誤表：わかりました。おそらく、継続的な統合の一部として生成されたプロジェクトに関連付けられたサイトにそれらを置くことができます。
興味深い読書リソースを提案したいと思います： https://leanpub.com/livingdocumentation
さらに、ユーザー向けのドキュメントであるかのように、開発者向けに記述されたドキュメントのみを評価します。 wikiまたはマークダウンのreadmeに記述された使用ガイド。その点で、githubにドキュメントがないことには同意しません。実際、他の開発者にオープンソースツールを使用してもらう唯一の方法は、明確な例が記載された包括的なreadmeを用意することです。
クラスがどのように相互作用するか、またはそれらがどのメソッドを持っているかについての核心は役に立たない。 IDEそのためです。
一部のメソッドで異常なことが起こっている場合、または魔法をかけるインテリジェントなアルゴリズムがある場合は、常に必要なだけコメント行を追加します。しかし、コードだけです。
高レベルでのみ文書化するプロジェクトのアーキテクチャ。データの格納またはフェッチの処理方法を書き留めてください。しかし、コードを見てもわかるすべてのものなので、これは、怠惰なプログラマーを叱る何かが必要な場合にのみ必要になる可能性があります。