6 ms·

Manuals (2014)

32 points by walterbell 3y ago

yread 3y ago
It's still there but way down: The sudoers file grammar will be described below in Extended Backus-Naur Form (EBNF). Don't despair if you are unfamiliar with EBNF; it is fairly simple, and the definitions below are annotated. Quick guide to EBNF EBNF is a concise and exact way of describing the grammar of a language. Each EBNF definition is made up of production rules. E.g., symbol ::= definition | alternate1 | alternate2 ...
- deleted 3y ago
  [deleted]
milliams 3y ago
(2014)
vsnf 3y ago
I understand it makes for a better joke, but there's no way that "how to read this manual" is higher on the problem causing dimension than "needs manual, doesnt have manual"
- karmakurtisaani 3y ago
  This is exactly how jokes work. Put them the other way around and you're left with a bland true statement. The point is to emphasize how bad "how to read this manual" manuals are, not actually to categorize manuals.
- PoignardAzur 3y ago
  Think correlation, not causation. Programs that can get away at all with not having a manual aren't going to be the most complicated ones. Kinda like how algorithms with O(N³) complexity have a reputation for being the most likely to screw you in production. It's not because O(N³) is worse than O(exp N), it's because O(exp N) will be noticed in testing whereas O(N³) is likely to have okay performance in testing and blow up with real-life inputs.
- Grumbledour 3y ago
  Depends on the manual. In my experience "How to read" either indicates the manual is borderline incomprehensible, or more often, the manual only describes trivial concepts that won't help you at all, for example, that clicking save will save the file. So in addition to not helping you understand, it will waste your time. Which can make it worse then having none.
- cal85 3y ago
  But any "needs manual, doesn't have manual" tool is less likely to be seriously relied upon in the first place, so it won't cause too many problems.
bogdan 3y ago
A bit of a boring reply but I think AIs have already solved this. AIs might not be able to handle lack of documentation but I think they solve the "How to read this manual" part. Anecdote: I've spent about 20 minutes trying to figure out how can I turn off a monitor with xrandr but still keep it's desktop contents in the same place and struggled to find anything useful, every single search result was about turning off the monitor conveniently missing the important part about keeping the contents there (I realize this is in part a DE/WM issue as well, I'm simplifying for the sake of this message). In any case, I've asked chatgpt and immediately suggesting setting brightness to 0 or using Xvfb to create a virtual buffer both solutions being satisfactory for what I needed.
kragen 3y ago
[flagged]
- zvmaz 3y ago
  I haven't read enough xkcd comics to say anything interesting about them, but would you agree that some man pages are hard to parse and don't necessarily help?
  - kragen 3y ago
    yes, and more generally there are many things that are unnecessarily difficult. but many other things are difficult because of their nature; there is no royal road to geometry or to nmr images i'll edit my comment above to clarify that
    - zvmaz 3y ago
      I understand. One time I wanted to understand what linux CGroups are, this is what I read in the official linux manual: > Control Groups provide a mechanism for aggregating/partitioning sets of tasks, and all their future children, into hierarchical groups with specialized behaviour. > Definitions: > A cgroup associates a set of tasks with a set of parameters for one or more subsystems [...]. [1] Completely incomprehensible! [1] https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/cgroups.html https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1...
      - kragen 3y ago
        i don't find that example too bad, but maybe because i've been doing cgroupish things since last millennium with chroot, ptrace, ld.so hacks, virtual machines, etc., on different operating systems. a list of definitions like that is not a good introduction to the problem space this is an example where the inherent complexity of the problem space is significant, but unix adds a lot of unnecessary difficulty on top of it, and the documentation you linked is pure reference with no tutorial component, which is an unnecessarily difficult way to learn about it
thunderbong 3y ago
Mobile version https://m.xkcd.com/1343/ https://m.xkcd.com/1343/
deleted 3y ago
[deleted]
kragen 3y ago
this comic condemns spectroscopes, the integral and differential calculus, steam turbine electrical generators, c compilers, oscilloscopes, mixed integer linear program solvers like gmpl, clifford algebras, blender, climate models, and magnetic resonance imaging machines as tools that create enormously more problems than they solve. all of these tools require manuals which begin with instructions for how to read the manual. whether or not masked as humor, this kind of anti-intellectual nonsense has no place here anywhere, really, but especially here of course many tools are unnecessarily difficult, often because the person who designed them wasn't insightful enough to simplify them, or because they're badly explained. and that does create problems, sometimes more problems than the tool solves. but many other problems are difficult to solve by their nature, and there are limits to how much tools can simplify them there is no royal road to geometry, and blaming geometers for that fact doesn't change it
- iainmerrick 3y ago
  Who mentioned geometry? And I think you’re interpreting “tools” rather more widely than intended by the strip.
  - kragen 3y ago
    what kind of tools do you think the strip intended to refer to? i gave ten examples, you can hopefully give at least three or four
    - iainmerrick 3y ago
      Command-line tools, and appliances, are the two categories that came to mind.
      - kragen 3y ago
        such as spectroscopes, c compilers, oscilloscopes, and mixed integer linear program solvers like gmpl? i feel like condemning those for starting their manuals with instructions for reading the manual is pretty bad even if we don't include geometry as a 'tool'

Manuals (2014)

32 points by walterbell 3y ago

It's still there but way down: The sudoers file grammar will be described below in Extended Backus-Naur Form (EBNF). Don't despair if you are unfamiliar with EBNF; it is fairly simple, and the definitions below are annotated. Quick guide to EBNF EBNF is a concise and exact way of describing the grammar of a language. Each EBNF definition is made up of production rules. E.g., symbol ::= definition | alternate1 | alternate2 ...

deleted 3y ago
[deleted]

milliams 3y ago

(2014)

vsnf 3y ago

I understand it makes for a better joke, but there's no way that "how to read this manual" is higher on the problem causing dimension than "needs manual, doesnt have manual"

karmakurtisaani 3y ago
This is exactly how jokes work. Put them the other way around and you're left with a bland true statement. The point is to emphasize how bad "how to read this manual" manuals are, not actually to categorize manuals.
PoignardAzur 3y ago
Think correlation, not causation. Programs that can get away at all with not having a manual aren't going to be the most complicated ones. Kinda like how algorithms with O(N³) complexity have a reputation for being the most likely to screw you in production. It's not because O(N³) is worse than O(exp N), it's because O(exp N) will be noticed in testing whereas O(N³) is likely to have okay performance in testing and blow up with real-life inputs.
Grumbledour 3y ago
Depends on the manual. In my experience "How to read" either indicates the manual is borderline incomprehensible, or more often, the manual only describes trivial concepts that won't help you at all, for example, that clicking save will save the file. So in addition to not helping you understand, it will waste your time. Which can make it worse then having none.
cal85 3y ago
But any "needs manual, doesn't have manual" tool is less likely to be seriously relied upon in the first place, so it won't cause too many problems.

bogdan 3y ago

A bit of a boring reply but I think AIs have already solved this. AIs might not be able to handle lack of documentation but I think they solve the "How to read this manual" part. Anecdote: I've spent about 20 minutes trying to figure out how can I turn off a monitor with xrandr but still keep it's desktop contents in the same place and struggled to find anything useful, every single search result was about turning off the monitor conveniently missing the important part about keeping the contents there (I realize this is in part a DE/WM issue as well, I'm simplifying for the sake of this message). In any case, I've asked chatgpt and immediately suggesting setting brightness to 0 or using Xvfb to create a virtual buffer both solutions being satisfactory for what I needed.

kragen 3y ago

[flagged]

zvmaz 3y ago
I haven't read enough xkcd comics to say anything interesting about them, but would you agree that some man pages are hard to parse and don't necessarily help?
- kragen 3y ago
  yes, and more generally there are many things that are unnecessarily difficult. but many other things are difficult because of their nature; there is no royal road to geometry or to nmr images i'll edit my comment above to clarify that
  - zvmaz 3y ago
    I understand. One time I wanted to understand what linux CGroups are, this is what I read in the official linux manual: > Control Groups provide a mechanism for aggregating/partitioning sets of tasks, and all their future children, into hierarchical groups with specialized behaviour. > Definitions: > A cgroup associates a set of tasks with a set of parameters for one or more subsystems [...]. [1] Completely incomprehensible! [1] https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/cgroups.html https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1...
    - kragen 3y ago
      i don't find that example too bad, but maybe because i've been doing cgroupish things since last millennium with chroot, ptrace, ld.so hacks, virtual machines, etc., on different operating systems. a list of definitions like that is not a good introduction to the problem space this is an example where the inherent complexity of the problem space is significant, but unix adds a lot of unnecessary difficulty on top of it, and the documentation you linked is pure reference with no tutorial component, which is an unnecessarily difficult way to learn about it

thunderbong 3y ago

Mobile version https://m.xkcd.com/1343/ https://m.xkcd.com/1343/

deleted 3y ago

[deleted]

kragen 3y ago

this comic condemns spectroscopes, the integral and differential calculus, steam turbine electrical generators, c compilers, oscilloscopes, mixed integer linear program solvers like gmpl, clifford algebras, blender, climate models, and magnetic resonance imaging machines as tools that create enormously more problems than they solve. all of these tools require manuals which begin with instructions for how to read the manual. whether or not masked as humor, this kind of anti-intellectual nonsense has no place here anywhere, really, but especially here of course many tools are unnecessarily difficult, often because the person who designed them wasn't insightful enough to simplify them, or because they're badly explained. and that does create problems, sometimes more problems than the tool solves. but many other problems are difficult to solve by their nature, and there are limits to how much tools can simplify them there is no royal road to geometry, and blaming geometers for that fact doesn't change it

iainmerrick 3y ago
Who mentioned geometry? And I think you’re interpreting “tools” rather more widely than intended by the strip.
- kragen 3y ago
  what kind of tools do you think the strip intended to refer to? i gave ten examples, you can hopefully give at least three or four
  - iainmerrick 3y ago
    Command-line tools, and appliances, are the two categories that came to mind.
    - kragen 3y ago
      such as spectroscopes, c compilers, oscilloscopes, and mixed integer linear program solvers like gmpl? i feel like condemning those for starting their manuals with instructions for reading the manual is pretty bad even if we don't include geometry as a 'tool'