|
Top-level
 OR maybe the docs are terrible. Perhaps they're written for experts instead of users. Maybe present a few example commands at the top instead of at the bottom of 20 pages of man output. It's like saying "To code, you need to know ancient Sumerian." 37 comments
 @jrconlin @mhoye there's definitely a difference between a technical reference manual and a user guide. General function belongs in the latter. But by its very nature, it's going to be lengthy, particularly if a lot of basic concepts need to be introduced. Complaining "tl;dr" is bogus if the necessary information is present and concisely delivered.  If you're telling people that the solution to navigating bad documentation is to learn regular expressions, then I don't even know what to say. That's like telling somebody who's struggling to climb a mountain that why don't you just learn how to fly? Anyway, here's what you get when you use gcc to compile Hello World, with single quotes instead of double quotes. Not, please: those are warnings, not errors. The compile actually finishes and produces an executable. @mhoye I'm not sure what you're trying to illustrate with that example. You seem to be suggesting that compilers should be friendly enough to be usable by people who don't know the programming language. A C programmer has to know the difference between a character constant and a string literal, and what a multicharacter constant is. It's not the tool's job to teach the language syntax.  @a @mhoye The tool can't read the programmer's mind. Perhaps the "not a string literal" message should have been an error instead of a warning, since it clearly doesn't conform to the function signature. But beyond that, the programmer should know the difference between a string literal and any other data type. That's basic knowledge of the language. Knowing printf's signature is too, that's part of the language spec. Ancient Sumerian is the oldest form of written language, and there are numerous translation texts available. Surely, it's no challenge to the modern reader. To presume that someone has skill or knowledge is to exclude a large number of people. Everyone has their own skill sets. Your skills are not as important to others. 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. 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". It also presumes that there is only one logical path for information to take, when that's seldom the case. It's also why books have tables of contents and indexes. (I'll also note that the most popular track on that album comes fifth, and it's not like folk are always listening to everything that comes before it.)  |
Gregory's Server
@jrconlin @mhoye fulltext search, regexp search are well established features. If all you want is an example it doesn't matter that it's at the end of a 20page document, all that matters is that it's present.