4 ms·
"the manual" is a form of communication for humans. Something nix has been de-prioritizing for thirty years! By experience, the nix culture has been "if you do
by mistrial9 8y ago
"the manual" is a form of communication for humans. Something nix has been de-prioritizing for thirty years! By experience, the nix culture has been "if you do not understand this, you should not be here" and a low-level hostility towards questions and learning, comes from some science gestalt in the 1800's German or something.
*nix is friendly, it is just selective in who its friends are" .. is a dot-signature from that era
A manual is a reading experience, a working reference system, and relies on the visual context it is presented in. There are vast differences in the quantitative and qualitative contents of manuals, on the same content! The BASH man page is .. improving ?
Specifically compare an alphabetized list of every option, including "change the preferred shortcut" and "let the sea-water in, thereby killing everyone if you are underwater" .. are right next to each other .. to modern manuals in say, the Python culture. Specifically compare say, huge amounts of text supplied for some obscure option that is not at all needed, to a terse one-liner for something crucial that is used everyday.
The parent comment cheerfully "blames the victim" with implied guilt for "not reading the manual" as if more time and effort on the part of the user, is the answer to the communication problem posed with such a dense and subtle realm.
Last thing in this rant is, that a small interesting article on something specific is an antidote to the largely unsolvable challenge here, so good on that.
- blattimwind 8y ago> a low-level hostility towards questions and learning, comes from some science gestalt in the 1800's German An oddly specific comparison.
- detaro 8y agoI don't think you can generalize that. E.g. some of the BSDs pride themselves in great documentation. The shell manuals are not just alphabetical lists, but sort-of guides to their programming languages. etc.
- nwatson 8y ago> The BASH man page is .. improving? When I had to start dealing with bash a lot about 5 years ago I consulted "Greg's Bash Wiki" at https://mywiki.wooledge.org/BashGuide https://mywiki.wooledge.org/BashGuide and it pretty comprehensively treats best practices for writing bash scripts. I often go back to consult the guide.
- tomkwong 8y agoNowadays, people just skip the manual and go to stack overflow. The best way to learn something is still RTFM.
- js2 8y ago> Something nix has been de-prioritizing for thirty years! By experience, the nix culture has been "if you do not understand this, you should not be here" This is an open-source thing. Hardly anyone wants to write documentation that isn’t paid to do so. There’s no glory in it. I first learned Unix on SunOS/Solaris and the man pages were excellent. You could start with “man intro” and learn your way around the entire system from there. BTW, if you think you’re any good at documentation, open-source needs your help. It’s a great way to contribute.
- jonahx 8y ago> Hardly anyone wants to write documentation that isn’t paid to do so. There’s no glory in it. There actually is glory in it. Many (granted, not all) popular, celebrated open source projects got that way by having a great user experience with intuitive, accessible docs. I actually think that most programmers (even many very good ones) are simply bad at writing docs. They actually can't do it well. Or it would be a monumental effort for them to do it well. It really is a different skill set.
- BurningFrog 8y agoIs writing docs really that different a skill from writing readable code? Or are these "great programmers" not actually that good at that?
- jonahx 8y ago> Is writing docs really that different a skill from writing readable code? It is correlated (though probably not perfectly) with writing readable code. But that is a different skill from writing useful, correct software. That is, you can write useful, correct software whose code is difficult for others to understand and maintain.
- thatoneuser 8y agoRight? So much elitism. It's no wonder stack overflow is visited by ALL Unix users while the man pages waste away.