7 ms·

I'm with parent, even my bad READMEs took a lot of time. Consumers of open source are just so damn entitled. It's discouraging.

ubernostrum 8y ago
OK. I use a very similar set of heuristics to what's described in this post. Here's the documentation for the most recent thing I released: https://django-registration.readthedocs.io/en/3.0/ https://django-registration.readthedocs.io/en/3.0/ And the one before that: https://pwned-passwords-django.readthedocs.io/en/1.3.1/ https://pwned-passwords-django.readthedocs.io/en/1.3.1/ Here's the next of my packages that I'm working on, not because the code needs work but because the documentation isn't up to my standards anymore (in fact, I'm doing a rolling refresh of all my personal packages right now): https://webcolors.readthedocs.io/en/1.8.1/ https://webcolors.readthedocs.io/en/1.8.1/ I don't expect everyone else to match my output in documentation. I do expect people to write some type of prose documentation covering more than just "here's an auto-generated API reference, good luck", or "here's a README with a couple examples, good luck". And I absolutely treat quality of documentation as a predictor for quality of code, because it tends to be a pretty strong predictor. Want to tell me how "entitled" I am?
- kkarakk 8y ago
  fantastic work, I agree with you - most of the time the "documentation" for open source work is done by more experienced devs answered questions from noobs on forums like stack overflow and this is a crazy state to live in
- anothergoogler 8y ago
  > Want to tell me how "entitled" I am? Sorry I didn't notice the provocation until now! You are very entitled, and you overestimate how much time most people have to contribute to open source projects. I'm happy if a FLOSS project even provides moderately recent API docs, which apparently upset you. For what it's worth, I attribute most of Django's success to its top-notch documentation. I've shipped large Django projects and think it's solid software, and I greatly appreciate your contributions. At the same time I recognize that Django won what is essentially a popularity contest. Web frameworks are a crowded space and beginner-friendly docs are required. If I'm open sourcing a library that is the only one of its kind, priorities differ. I don't think you recognize that difference, and you're judging other projects as you would a web framework. Some of the best libraries I've used came with little more than API docs. Selecting open source libraries by the quality of their documentation is a risky practice, to say the least.
- JdeBP 8y ago
  Note that "anothergoogler" said that consumers of open source were acting as though entitled, not producers.
  - ubernostrum 8y ago
    Well, I'm both a producer and a consumer of open source code. So is Eric, who wrote the "entitled" post being complained about.

ubernostrum 8y ago

OK. I use a very similar set of heuristics to what's described in this post. Here's the documentation for the most recent thing I released: https://django-registration.readthedocs.io/en/3.0/ https://django-registration.readthedocs.io/en/3.0/ And the one before that: https://pwned-passwords-django.readthedocs.io/en/1.3.1/ https://pwned-passwords-django.readthedocs.io/en/1.3.1/ Here's the next of my packages that I'm working on, not because the code needs work but because the documentation isn't up to my standards anymore (in fact, I'm doing a rolling refresh of all my personal packages right now): https://webcolors.readthedocs.io/en/1.8.1/ https://webcolors.readthedocs.io/en/1.8.1/ I don't expect everyone else to match my output in documentation. I do expect people to write some type of prose documentation covering more than just "here's an auto-generated API reference, good luck", or "here's a README with a couple examples, good luck". And I absolutely treat quality of documentation as a predictor for quality of code, because it tends to be a pretty strong predictor. Want to tell me how "entitled" I am?

kkarakk 8y ago
fantastic work, I agree with you - most of the time the "documentation" for open source work is done by more experienced devs answered questions from noobs on forums like stack overflow and this is a crazy state to live in
anothergoogler 8y ago
> Want to tell me how "entitled" I am? Sorry I didn't notice the provocation until now! You are very entitled, and you overestimate how much time most people have to contribute to open source projects. I'm happy if a FLOSS project even provides moderately recent API docs, which apparently upset you. For what it's worth, I attribute most of Django's success to its top-notch documentation. I've shipped large Django projects and think it's solid software, and I greatly appreciate your contributions. At the same time I recognize that Django won what is essentially a popularity contest. Web frameworks are a crowded space and beginner-friendly docs are required. If I'm open sourcing a library that is the only one of its kind, priorities differ. I don't think you recognize that difference, and you're judging other projects as you would a web framework. Some of the best libraries I've used came with little more than API docs. Selecting open source libraries by the quality of their documentation is a risky practice, to say the least.
JdeBP 8y ago
Note that "anothergoogler" said that consumers of open source were acting as though entitled, not producers.
- ubernostrum 8y ago
  Well, I'm both a producer and a consumer of open source code. So is Eric, who wrote the "entitled" post being complained about.