なぜこれほど多くのライブラリにドキュメントがない/不十分なのですか？[閉まっている]

同様に、オープンソースプロジェクトの設計やアーキテクチャに関するドキュメントがなくても成功する方法はありますか？質問、私は好奇心が強いです：なぜこれほど多くのライブラリがエンドユーザーのドキュメントにそれほど欠けているのですか？

私の見解はこれです：

1. ほとんどの人は、ソースコードを書くよりもソースコードを読むのが難しいことに同意します。
2. ドキュメントがなければ、ライブラリを使用するにはライブラリのソースコードを読む必要があります。
3. したがって、文書化されていないライブラリを使用することは、ライブラリをゼロから再作成するだけではありません。
4. その結果、人々にライブラリを使用してもらいたい場合は、文書化されていることを確認してください。

多くの開発者がドキュメントを書くことを好まないことは知っていますし、退屈な作業になる可能性があることに同意します。しかし、それは不可欠な仕事です。世界で最高のプログラマーインターフェースを持つよりも、ライブラリに優れたドキュメントがあることが重要です。（人々は常にくだらないライブラリを使用します;文書化されていないライブラリを使用する人はほとんどいません）

ああ、ドキュメントを言うとき、私は本当のドキュメントを意味することに注意してください。Sandcastle / Javadoc / Doxygenボイラープレートではありません。

ほとんどの場合、開発者は気にすることはないので、あなたはほとんどあなた自身の質問に答えたと思います。この問題は、ボランティアプロジェクトで特によく見られます。

ただし、別の大きな問題があると思います。多くの場合、開発者はライブラリの動作の全体的なモデルを実際に開発していません（または、そのモデルを明確に表現するのに苦労しています）。残念ながら、そのモデルを明確にし、ソフトウェアの各部分がどのように適合するかは、ドキュメントの最も重要な部分であることがよくあります。

典型的な場合、書かれているものは非常に高レベルの概要（「これはかっこいいことをするためのライブラリです！」）と非常に低レベルの説明（各関数に渡される各パラメーターのタイプと説明）があります。残念ながら、物事がどのように機能するか、ピースがどのように適合するかなどの一般的な理論について中級レベルが存在することはめったにありません。これの多くは、開発者が彼らを形成、合理化、または理解しようとしていないことが多いという事実に遡りますその特定の詳細レベルのコード。少なくとも私が見たいくつかのケースでは、そのレベルでドキュメントを書くように依頼された開発者は、それが非常に問題があることを発見しました-多くの人がコードを書き直したいと思ったので、詳細。

その抽象化レベルでうまく書くことはしばしば困難です-そして、開発者がその抽象化レベルでそれについて本当に考えていなかったなら、彼らはしばしばコードがいくらか恥ずかしいと思うでしょう、そして彼らが幸せになる前にそれを書き直したいかもしれませんそれをリリースすることについて。

開発者がコードに非常に包まれているために、それがどのように機能するかが「明らか」であり、なぜ他の人には明らかでないのかを見ることができないからだと思います。同様に、多くの製品Webサイトが製品の素晴らしさを語っていますが、実際にその機能を教えてはいけません！

あなたは自分で答えを指摘しました：

多くの開発者がドキュメントを書くことを好まないことは知っていますし、退屈な作業になる可能性があることに同意します。

プログラマーとして、私たちはコードを書くことを楽しんでいますが、ドキュメントを書くことを楽しんでいる人はほとんどいません。

優れたコーダーは優れたドキュメントの価値を知っていますが、それを適切に行うにはかなりの時間がかかります。それは楽しくなく、長い時間がかかるので、「後で行う」パイルに入れられるため、満足のいくレベルに達することはありません。

サイドノートとして、プログラマーが自分の製品に関するドキュメントを書くことも非常に困難です。彼らはシステムを非常によく知っているので、特定のことは彼らにとって明らかです。これらの部分は、消費者に明らかではないにもかかわらず、しばしば言及されることはありません。

ドキュメントの作成はスキルです。すべてのスキルと同様に、練習が必要です。コードの作成に費やす時間と労力は、すぐに見返りがあります。新しい機能、修正されたバグ、改善された速度を見ることができます。ドキュメンテーションの作成には、遅れが生じます。新しい人々がコードに取り組む必要があるとき、または数か月後または数年後にコードに取り組むために戻ってきた場合、それは長期的に役立ちます。短期に焦点を当てるのは当然のことです。

私の意見では、優れたドキュメントを書く能力は、優秀なプログラマーと平凡なプログラマーを区別する重要な特徴の1つです。

ドキュメンテーションを書くのに最も適した人は、そうする動機が最も低い人でもあります。

彼（または彼女）は：

• ユーザーではなく、主にライブラリのメンテナーです。そのため、ライブラリが小さくシンプルであればあるほど、彼の仕事は簡単になります。コードに加えて小説の半分を維持すると、彼の仕事は難しくなりますが、
• 彼はライブラリを完全に知っているので、ドキュメントは必要ありません。
• 彼はプログラマであり、ドキュメントではなくコードを書きたいと思っています。

「うーん、このための適切なドキュメントを書くのに数時間を費やすべきだ」と思う人は誰もいません。なぜ彼は？

そしてもちろん、自動生成されたdoxygenスタイルのコメントがドキュメンテーションに関して必要なものであるというこの都市の伝説があることはおそらく助けにはなりません。

そうであっても、開発者が実際にまれに喜んで書き込みドキュメントには、開発者が必要とされているすべてはあなたのような宝石を伝える、いくつかのようにコメントを記入していることを考えることに、このカルトによって洗脳されていることを50/50のチャンスですその「関数Foo getFoo()はFoo型のオブジェクトを返し、Fooオブジェクトを取得するために使用されます」。

ドキュメンテーション？臭い文書は必要ありません！

コードの仕組みを知っているのに、なぜコードをドキュメント化するのに時間を費やす必要があるのですか？それに加えて、私はこのプロジェクトを金曜日までに終わらせなければならず、私はそれをそのままにするつもりはほとんどありません...