Manuals (2014) | Hacker News Reader

Manuals (2014)

xkcd.com

32 pointswalterbell33 comments

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 ...

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"

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.

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.

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.

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.

(2014)

Mobile version

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

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

Who mentioned geometry?

And I think you’re interpreting “tools” rather more widely than intended by the strip.

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

Command-line tools, and appliances, are the two categories that came to mind.

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'

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.

Reply on news.ycombinator.com