I’ve published Open Source code and documentation. It is a lot of work.
I think that “How I judge someone’s else hours of effort in 30 seconds” is a toxic attitude.
I think that “How I judge someone’s else hours of effort in 30 seconds” is a toxic attitude.
Say some random project has 10 stars on github and no commits in the past 2 years. Good documentation and working examples could be the difference between using it and not using it. If you only have a single day to spike the feature, you need to efficiently explore possible solutions.
Obviously, this depends on many factors. How critical is the feature? What are the alternatives? How long would implementing it in house take? And so on.
Here's the documentation for the most recent thing I released:
https://django-registration.readthedocs.io/en/3.0/
And the one before that:
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/
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?
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.
So is Eric, who wrote the "entitled" post being complained about.
If your idea of shopping for dependencies is looking at the amount of GitHub stars and the quality of the documentation: you are going to miss some real diamonds in the rough.
It's about how he should best spend his time, which is finite, after all. Paid time even more so.
I evaluate projects by (1) actually reading their source code, (2) looking up their frequency of updates and release packaging, (3) the community interaction of authors and contributors.
The total amount of effort it took to write that blog post could have been spent on submitting PRs to improve documentation of various projects.
People who put in the effort to have good documentation are more likely to also be producing good software that's worth the time I'll put into trying to learn it.
And no matter how righteous you want to get here on HN in proclaiming that to be "toxic" and trying to read it uncharitably, I'd bet all the money in my wallet right now that you have 30-second heuristics you use to judge whether a piece of software is worth your time to explore.
Hell, I've thrown some undocumented projects out there with the intention of cleaning them up later or if it gains traction. I have so many side projects that I couldn't possibly reasonably document them all.