5 ms·

Great! If you can answer those questions, send a pull request to add it to the docstring. You've spent some time thinking of those questions, so you'd write a v

Great! If you can answer those questions, send a pull request to add it to the docstring. You've spent some time thinking of those questions, so you'd write a very complete docstring. Complaining will not solve the issue. Sending a PR will solve it. This is what I was saying above. I am attempting to orient people into the "open-contribution" community, where we share the opinion that free software is NOT free to produce. Someone must do the things you are suggesting at some point if they are to exist, and who better than yourself? With regards to your last paragraph, a common misconception is that a "payment" of open-source software is number of users. That would be true for proprietary software where payment = number of users * price, but for open-source software the developers couldn't care less (except maybe superficially, but this mental reward is insignificant for the long-term motivation for a project). They want to make a library that solves their own problems and is stable. They allow people to help improve the library in exchange for releasing it for their unrestricted use. Otherwise, there is little motivation to release it. When I find a new library that solves a problem in an interesting way, I learn using whatever is available (existing documentation, headers, source, and examples) and write down the difficult parts. The price I pay for using the software is to send my notes back to the developers in a polished, organized form that is consistent with their existing documentation. Then, no one needs to repeat what I've done in the future.

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.
rendaw 8y ago
There are times when people report an issue to an open source project and the response is "You should fix it yourself". Open source contribution happens when the contributor has invested themself in the project and wants to maintain the relationship. Perhaps the requester is evaluating multiple packages and wants to inform the project why they're going with another one instead. Maybe they got to the point in their evaluation that they're ready to commit only to discover a critical issue hidden in the (lack of) documentation. It also comes off as hostile since implies that the requester's time is less valuable than the project maintainer's. Perhaps the requester is busy contributing to other open source projects. Perhaps the requester only has time right now to use the software, but has the goal of contributing in the future. The project's maintainer's responsibility is maintaining the software, presumably because of some personal interest. Reporting and even expecting them to fix issues is absolutely normal.
- matheusmoreira 8y ago
  >implies that the requester's time is less valuable than the project maintainer's It is. In large projects, there are relatively few maintainers responsible for evaluating the requests, reports and code from lots of people. They're scarce resources. https://www.youtube.com/watch?v=fMeH7wqOwXA https://www.youtube.com/watch?v=fMeH7wqOwXA https://www.slideshare.net/linaroorg/maintainer https://www.slideshare.net/linaroorg/maintainer
- jancsika 8y ago
  I find if you maintain an open source project as if your users were customers, things tend to go pretty smooth.
  - yawaramin 8y ago
    Can you explain how you found that?
    - jancsika 8y ago
      By trying it, and realizing afterwards that nothing bad happened as a consequence. The main benefit is that it forces one to try to be professional and consistent, and to avoid being flippant, cryptic, didactic, and condescending. Keep in mind that cutting customers loose is a natural part of the game, too. If someone demands to get a Big Mac at Chipotle there's no law that says they get to block the line for eternity.
weberc2 8y ago
Some people just want to use a library. Not everyone wants to build a library. When evaluating a candidate library, it’s perfectly reasonable to look at things like documentation completeness. “Don’t discuss weaknesses; fix them” isn’t helpful or constructive. There is no moral commandment to pretend all open source libraries are without flaws.
kazinator 8y ago
geofft could just ignore the library completely without giving his valuable opinions on the kinds of things that should be specified in a reference document. That isn't complaining at all. Maybe the author really has no clue on what information to put into an API document; geofft's comment provides stimulating ideas. geofft doesn't have an "issue" because he's not using the library; he can avoid the non-documentation problem for himself quite adequately by ignoring the library and moving to a different one. > If you can answer those questions, No you can't. You can only reverse engineer what the code does, not what the programmer intended. Why would I sit there reverse engineering someone's code to write a document for them which codifies the bugs they didn't intend to make? They will just reject the doc "oh, thanks for writing this but that's not what's supposed to happen; that's a bug. Can you wait until next release and then change your document based on the new code? Thanks.". Fuck that, you know? Will the designer even take the document seriously going forward? Or will he just regard that as someone else's unimportant opinion about what a particular revision of his program did once upon a time? We already know something about the designer's attitude is toward documentation, from the lack of it. Satellite documentation: different story. I mean, tutorials, guides to internals and things like that. But, no, I'm not writing the basic, fundamental spec for your undocumented code you've already written.
geofft 8y ago
> I am attempting to orient people into the "open-contribution" community, where we share the opinion that free software is NOT free to produce. I agree with this position. I am also working on my own open-source projects, as well as other projects that I know have conscientious maintainers and a high-quality community. Why should I contribute my time to this project? To be a little blunt: if this project has not thought about things like ownership of pointers and concurrency safety, it is not a project I think other people should use. My time is limited, and I use it on improving projects that I think are worth improving. > for open-source software the developers couldn't care less (except maybe superficially, but this mental reward is insignificant for the long-term motivation for a project). They want to make a library that solves their own problems and is stable. As an open-source maintainer, this doesn't describe me at all. I care more about things that improve the world than things that amuse me. (I also work on a few things that amuse me, but they're relatively clear about that status, and f they're not, I welcome someone calling me out on it.) All the long-term projects I work on are motivated by wanting that project to be a healthy project available as a compelling option for as many people as possible. I had the rather delightful experience of starting a new job recently and finding that the next team over had just decided to start using a project I've been maintaining for a few years. If I had not spent time writing both code and documentation that welcomed unknown future users, this would never have happened. (And I still have not written nearly enough documentation for it!) If my motivation were just filling my own needs, I probably wouldn't publish software at all. If it were that plus bolstering my personal brand, it would go on my blog or as CC-BY-NC-ND or something. My entire motivation for releasing software under a free license is for other people to use it.

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.

rendaw 8y ago

There are times when people report an issue to an open source project and the response is "You should fix it yourself". Open source contribution happens when the contributor has invested themself in the project and wants to maintain the relationship. Perhaps the requester is evaluating multiple packages and wants to inform the project why they're going with another one instead. Maybe they got to the point in their evaluation that they're ready to commit only to discover a critical issue hidden in the (lack of) documentation. It also comes off as hostile since implies that the requester's time is less valuable than the project maintainer's. Perhaps the requester is busy contributing to other open source projects. Perhaps the requester only has time right now to use the software, but has the goal of contributing in the future. The project's maintainer's responsibility is maintaining the software, presumably because of some personal interest. Reporting and even expecting them to fix issues is absolutely normal.

matheusmoreira 8y ago
>implies that the requester's time is less valuable than the project maintainer's It is. In large projects, there are relatively few maintainers responsible for evaluating the requests, reports and code from lots of people. They're scarce resources. https://www.youtube.com/watch?v=fMeH7wqOwXA https://www.youtube.com/watch?v=fMeH7wqOwXA https://www.slideshare.net/linaroorg/maintainer https://www.slideshare.net/linaroorg/maintainer
jancsika 8y ago
I find if you maintain an open source project as if your users were customers, things tend to go pretty smooth.
- yawaramin 8y ago
  Can you explain how you found that?
  - jancsika 8y ago
    By trying it, and realizing afterwards that nothing bad happened as a consequence. The main benefit is that it forces one to try to be professional and consistent, and to avoid being flippant, cryptic, didactic, and condescending. Keep in mind that cutting customers loose is a natural part of the game, too. If someone demands to get a Big Mac at Chipotle there's no law that says they get to block the line for eternity.

weberc2 8y ago

Some people just want to use a library. Not everyone wants to build a library. When evaluating a candidate library, it’s perfectly reasonable to look at things like documentation completeness. “Don’t discuss weaknesses; fix them” isn’t helpful or constructive. There is no moral commandment to pretend all open source libraries are without flaws.

kazinator 8y ago

geofft could just ignore the library completely without giving his valuable opinions on the kinds of things that should be specified in a reference document. That isn't complaining at all. Maybe the author really has no clue on what information to put into an API document; geofft's comment provides stimulating ideas. geofft doesn't have an "issue" because he's not using the library; he can avoid the non-documentation problem for himself quite adequately by ignoring the library and moving to a different one. > If you can answer those questions, No you can't. You can only reverse engineer what the code does, not what the programmer intended. Why would I sit there reverse engineering someone's code to write a document for them which codifies the bugs they didn't intend to make? They will just reject the doc "oh, thanks for writing this but that's not what's supposed to happen; that's a bug. Can you wait until next release and then change your document based on the new code? Thanks.". Fuck that, you know? Will the designer even take the document seriously going forward? Or will he just regard that as someone else's unimportant opinion about what a particular revision of his program did once upon a time? We already know something about the designer's attitude is toward documentation, from the lack of it. Satellite documentation: different story. I mean, tutorials, guides to internals and things like that. But, no, I'm not writing the basic, fundamental spec for your undocumented code you've already written.

geofft 8y ago

> I am attempting to orient people into the "open-contribution" community, where we share the opinion that free software is NOT free to produce. I agree with this position. I am also working on my own open-source projects, as well as other projects that I know have conscientious maintainers and a high-quality community. Why should I contribute my time to this project? To be a little blunt: if this project has not thought about things like ownership of pointers and concurrency safety, it is not a project I think other people should use. My time is limited, and I use it on improving projects that I think are worth improving. > for open-source software the developers couldn't care less (except maybe superficially, but this mental reward is insignificant for the long-term motivation for a project). They want to make a library that solves their own problems and is stable. As an open-source maintainer, this doesn't describe me at all. I care more about things that improve the world than things that amuse me. (I also work on a few things that amuse me, but they're relatively clear about that status, and f they're not, I welcome someone calling me out on it.) All the long-term projects I work on are motivated by wanting that project to be a healthy project available as a compelling option for as many people as possible. I had the rather delightful experience of starting a new job recently and finding that the next team over had just decided to start using a project I've been maintaining for a few years. If I had not spent time writing both code and documentation that welcomed unknown future users, this would never have happened. (And I still have not written nearly enough documentation for it!) If my motivation were just filling my own needs, I probably wouldn't publish software at all. If it were that plus bolstering my personal brand, it would go on my blog or as CC-BY-NC-ND or something. My entire motivation for releasing software under a free license is for other people to use it.