|
Top-level
True, but you're also far more likely to find someone translate from French than Sumerian. Thus why we now have TL;DR and Stack Overflow. If I found out more people read someone else's summary of a tool or library that I wrote, I'd do my best to work that summary in as my documentation. Maybe even take a few pointers about how to present information better as well. 21 comments
Uhm, maybe they wrote it because they don't understand how to submit a PR? (Again, different skill sets and not wanting to learn Sumerian. That's why requiring knowledge from someone can make your life harder.) Maybe just reaching out to them would be enough, and a courteous thing to do anyway so that they get proper credit? Heck, even if they say "No", there are still lessons to be learned.  @jrconlin @mhoye not everything revolves around github PRs. A simple email "hey I wrote this summary for you" is all it would take to get the ball rolling. Putting the onus on the developer to reach out to the user for this is unsustainable and unrealistic. It would require constantly sifting the web to find these useful snippets. Whoever wrote the summary just has to hit Send on one email. Heh, and all the original doc writer had to do was get one editor. Which is pretty common and not difficult at all for any professional writer. Asking the audience to do that for him is unsustainable and unrealistic. The author wrote that up because they don't believe that the original source sufficiently solved their problem, nor would the be able to. Kinda damning, if you think about it. @jrconlin @mhoye so now you seem to be demanding that developers be professional writers. I suppose it's fair to expect professional writers to be employed by commercial software providers. Not fair to demand anything of open source; if no one steps up and volunteers then the audience has no one to blame but themselves. I'm asking that developers be aware of skills that may not be code based, yes.  @jrconlin @hyc @mhoye the solution to "there is a big gap between what maintainers provide and what users need" is not to ask overworked/underpaid FOSS maintainers to take on more responsibility. nor is it to deny the need exists. the solution is for the broader community to recognize the value of user-facing, newcomer-friendly docs and dedicated user support, and to help maintainers provide them. that requires investment. it's part of the broader open source collective action problem. I think it's also somewhat important to note scale. A tiny package used by a few folk probably doesn't need much more than what folk already do. This would probably not overburden that one guy in Nebraska. Once a project "graduates", takes on devs, and grows in use, then documentation becomes more important, just like security updates. Large projects should help by reaching down to smaller ones that they depend on. It would be more appropriate if you stopped asking and started doing, at least in the context of open source. The developers of any OS software have exactly zero obligation to fulfill random wishes of random dudes who happened to find their software useful. If you want to get it done, do it yourself or pay somebody to do it instead of wasting time to whine about it on the public internet instead of using a bug tracker.  My dude you have gone from "the problem is that people are stupid and illiterate" past "just learn regexes" straight to "asking developers to be competent at communicating in writing is bad", and you can fuck right off with all of that. You don't want to write docs, we get it. Just own the fact that you'd rather sneer at people than rub two synapses together to think about usability and leave it at that. @mhoye @jrconlin people write open source code because they saw a need and decided to address it. The fact that tech writers haven't also seen a similar need and stepped up to address it isn't the open source devs' fault. Demanding that someone who gave you a gift give it to you in a particular shape, size, and color is just being greedy. @mhoye @jrconlin to accuse me personally of not wanting to write docs is baseless. My LMDB project is thoroughly documented. Not only are the docs complete and easily accessible http://www.lmdb.tech/doc they're written in Doxygen, embedded in the source code and header files and always kept up to date with code changes. I feel like we're closing the circle here. I know that I am not a good enough writer or editor to presume that my docs are perfect. I also don't presume my audience is lazy or stupid. @hyc it reads like the basis of the disagreement here is not even your opinion/position, but your (incredibly frustrating) attempts to move the goalposts. If your immediate reaction to someone trying to call attention about how much something sucks had just involved you saying, "Yeah, that does suck. It's just that no one has put the time in to making it not suck yet," instead of what you actually did—engage in dithering apologetics—then you and @mhoye wouldn't be having this conversation. @hyc the goalpost moving comes across as worse than disinterest in fixing the problem. It's flak that has to be dodged by anyone on the path towards trying to get the problem fixed. Nobody in open source owes anyone else perfect jewels. But if lack of time/energy to put together a proper fix is at the root of the problem, questions remain about all the time and energy put into denying the problem existed and fervently arguing that everyone is just "illiterate and stupid". |
Gregory's Server
@jrconlin @mhoye that latter makes sense, but there's copyright issues to consider. Will the author of that summary grant you permission to incorporate their text into your docs? If so, why didn't they just contribute it to your project in the first place?