[snazz]

Man pages rarely are enough in my experience. When I encounter an issue with grub-install not writing to my EFI system partition, good luck finding much about it in its very short man page. You’ll have better luck using the ArchWiki, which is like a much better man page, but a simple Google search (or another search engine) will show a forum post with an easy solution as the very first result.

Piping six man pages through grep to find what I’m looking for is simply not as fast as Googling an error message.

I think there’s also a sort of cultural difference between languages and tools frequented by newer and older programmers: more experienced people look for documentation and then get working on their project, whereas less experienced programmers look for tutorials and very specific “soft” documentation.

Transitioning from modifying tutorials (the type-in-the-code-in-the-magazine of the 21st century) to glancing at the documentation is probably the surest sign of maturity. Still, you can get a ton done by copypasta.

This might have to do with learning to code with or without the Internet, I’m not sure. I’m personally very envious of people who can take a look at the docs and just get chopping without the assistance of the GIF-covered Medium posts.

[klez]

> When I encounter an issue with grub-install not writing to my EFI system partition, good luck finding much about it in its very short man page

This says more about the man pages for grub2 (and grub2 itself, to be honest) EDIT: than about manpages /EDIT.

Compare them with the man pages for grub1. There's a sea of difference.

If you really want to be blown away by a manpage, look for the one for mplayer, which is difficult to find information in for different reasons, i.e., lots of options and lots of options and flags that depend on other flags and options.

[umanwizard]

Yet another reason to prefer the BSD family of OSes over the GNU/Linux family.

In the BSDs, self-contained, complete, and correct documentation is a cultural value. Not one that’s always achieved, but a value nonetheless. Information missing from the man pages is a reportable bug.

And if the man page doesn’t document something, its code is right there in /usr/src for you to dig into.

[jnbiche]

Agreed. Even in Linux, complete documentation for userland tools is usually a given.

Not so with webdev. That said, the source code is there for all of us to read. I'm a frontend developer and spend more time looking at source code when I need to figure out an issue than digging through Medium posts. Particularly when something is behaving in an unexpected manner.

I'd urge everyone who hates webdev to try this approach the next time they struggle with an issue. JavaScript, for all its sins, is fairly easy to read. And once you've understood the ~30 most common gotchas in JS, reading the source is highly beneficial (and here's a good intro to those gotchas, including an accompanying video: https://github.com/denysdovhan/wtfjs)

Or better yet, work in one of the statically-typed compile-to-JS languages such as Typescript, ReasonML, Elm, ScalaJS, or Purescript and worry about those gotchas much less (and only when wrapping external libraries).