4 ms·

While I agree with the general thrust of what you're saying (people should contribute far more to the free software they use rather than be angry with maintaine

by cyphar 8y ago

While I agree with the general thrust of what you're saying (people should contribute far more to the free software they use rather than be angry with maintainers for not solving every issue under the sun -- and having more users is no substitute for having a few passionate external contributors), this is a fairly hostile way of trying to on-board people to a project. Not to mention that the developers that wrote the project in the first place are in a much better position to write documentation than anyone else (in the past I've had to review documentation from external contributors and I'm pretty sure it would've been phenomenally faster if I'd just written it in the first place -- it isn't their fault, it's just that I know the code and its history much better than them because I've maintained it).

vortico 8y ago
I agree that it's a somewhat hostile way to invite people to a project, but 1) I highly doubt that dropping a cheerful invite will have any convincing power other than someone replying "yeah, I should do that" and then promptly forgetting it, and 2) some scolding was needed. :) Your second point is a good one, but the developers are in a better position to write actual features and fix bugs than anyone else, and since documentation is more public-facing than source code, it's actually a better choice if someone wants to contribute anything at all, so the primary developers can spend their time more wisely. I certainly know the "phenomenally faster if I'd just written it in the first place" effect well, which is why I recommend to contributers to not do drive-by contributions but spend a good week writing notes while they use the library, and then convert to high-quality documentation, effectively adopting a section like you would with a community garden. Quality over quantity. And if the documentation attempt is low quality, it's still a much nicer way to prod the developer to write some documentation, so he/she can use it to define their quality standards or as a possible outline.
- saagarjha 8y ago
  > some scolding was needed Was it, really? I think the parent comments did a good job at pointing out a potential, actionable, flaw in this project. That doesn't mean that they should be "scolded" for pointing it out or that they themselves need to fix it.

by cyphar 8y ago

vortico 8y ago

I agree that it's a somewhat hostile way to invite people to a project, but 1) I highly doubt that dropping a cheerful invite will have any convincing power other than someone replying "yeah, I should do that" and then promptly forgetting it, and 2) some scolding was needed. :) Your second point is a good one, but the developers are in a better position to write actual features and fix bugs than anyone else, and since documentation is more public-facing than source code, it's actually a better choice if someone wants to contribute anything at all, so the primary developers can spend their time more wisely. I certainly know the "phenomenally faster if I'd just written it in the first place" effect well, which is why I recommend to contributers to not do drive-by contributions but spend a good week writing notes while they use the library, and then convert to high-quality documentation, effectively adopting a section like you would with a community garden. Quality over quantity. And if the documentation attempt is low quality, it's still a much nicer way to prod the developer to write some documentation, so he/she can use it to define their quality standards or as a possible outline.

saagarjha 8y ago
> some scolding was needed Was it, really? I think the parent comments did a good job at pointing out a potential, actionable, flaw in this project. That doesn't mean that they should be "scolded" for pointing it out or that they themselves need to fix it.