4 ms·

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 atti

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.

bArray 8y ago
Exactly, if everyone was held to this standard, there would be much less projects out there. 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.
- pvorb 8y ago
  By not documenting them you make clear that they're not intended for production use, which is perfectly valid in my opinion. I also do this a lot.
austinpray 8y ago
It’s toxic and lazy too. You should first go look and see if the actual code is high quality/does what you want. 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.
- rosser 8y ago
  Is it laziness or efficiency? It's, in my read, a heuristic (he even uses that word) for deciding whether it's worth spending time reading the docs before looking at the actual code, to see if it does what he wants. It's about how he should best spend his time, which is finite, after all. Paid time even more so.
  - Gigablah 8y ago
    It’s a really bad heuristic. 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.
    - deleted 8y ago
      [deleted]
dwaltrip 8y ago
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.
- anothergoogler 8y ago
  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
mwfunk 8y ago
The judging in this case is judging how much time a developer wants to spend investigating a project that they are are evaluating for their own use. I didn’t read it as being judgemental about other people’s work for its own sake.
ubernostrum 8y ago
If I'm looking for a library to solve a problem, and have a choice between multiple options, you'd better believe I'm going to have some "30 second" heuristics guiding me toward what's likely to be worth my time exploring further. 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.

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.

bArray 8y ago

Exactly, if everyone was held to this standard, there would be much less projects out there. 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.

pvorb 8y ago
By not documenting them you make clear that they're not intended for production use, which is perfectly valid in my opinion. I also do this a lot.

austinpray 8y ago

It’s toxic and lazy too. You should first go look and see if the actual code is high quality/does what you want. 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.

rosser 8y ago
Is it laziness or efficiency? It's, in my read, a heuristic (he even uses that word) for deciding whether it's worth spending time reading the docs before looking at the actual code, to see if it does what he wants. It's about how he should best spend his time, which is finite, after all. Paid time even more so.
- Gigablah 8y ago
  It’s a really bad heuristic. 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.
  - deleted 8y ago
    [deleted]

dwaltrip 8y ago

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.

anothergoogler 8y ago
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

mwfunk 8y ago

The judging in this case is judging how much time a developer wants to spend investigating a project that they are are evaluating for their own use. I didn’t read it as being judgemental about other people’s work for its own sake.

ubernostrum 8y ago

If I'm looking for a library to solve a problem, and have a choice between multiple options, you'd better believe I'm going to have some "30 second" heuristics guiding me toward what's likely to be worth my time exploring further. 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.