Hacker News Reader

Comment by dwaltrip | Hacker News Reader

It's often very useful to quickly evaluate a project. I don't think the author of this article intended any disrespect or to diminish someone's hard work. It's more about efficiently navigating a vast landscape of tools. Although, perhaps this could have been made more clear.

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.

View on HN

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.

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/

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?

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

> 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.

Note that "anothergoogler" said that consumers of open source were acting as though entitled, not producers.

Well, I'm both a producer and a consumer of open source code.

So is Eric, who wrote the "entitled" post being complained about.

Reply on news.ycombinator.com