• rumba@lemmy.zip
    link
    fedilink
    English
    arrow-up
    4
    ·
    23 hours ago

    I was always onboard to RTFM, that was my primary learning tool, but some of those fucking manuals were written by people who are entirely incapable of writing documents in a way that people who don’t already know the contents can understand it.

    Once you know something, almost any manpage is fine for reference, but few of the manpages actually teach you cleanly how to use a command from a beginner standpoint.

    • JigglySackles@lemmy.world
      link
      fedilink
      English
      arrow-up
      1
      ·
      7 hours ago

      That’s been my biggest gripe with man pages since I first tried Linux decades back. I couldn’t figure it out because most every page back then was written by an engineer for other engineers.

      • rumba@lemmy.zip
        link
        fedilink
        English
        arrow-up
        2
        ·
        7 hours ago

        There are occasional ones that are ok, man ip for example include examples, but you have to make it below lengthy Synopsis and Options

    • spizzat2@lemmy.zip
      link
      fedilink
      English
      arrow-up
      5
      ·
      23 hours ago

      Yes, at a minimum, I feel like every man page would be well served by a single example near the top that is something like

      Common Usage:

      grep [what] [where]

      e.g.

      grep “search string” *.txt

      Instead it’s “grep [-the entire alphabet, twice] [-12 other options you probably won’t use] [cryptic arguments]”

      The description is helpful, at least.

      • neclimdul@lemmy.world
        link
        fedilink
        English
        arrow-up
        2
        ·
        7 hours ago

        most man man pages have an example section. its at the bottom because man pages are optimized as a reference since that’s what you use them for most.

        that said, greps example section is obtuse so a couple more straight forward examples would probably serve it well.

        i think the bigger problem with the rtfm response is we often dont know what we know. The Unix/Linux software systems have ton of internalized knowledge. everything is a file. comfort on a cli shell. pipes and chaining cli programs. common command arguments and man page structures. Tons I’m forgetting I’m sure.

        If you have all those things internalized, a quick trip to man is probably all you need. But if someone’s asking, that isnt true, and you need to coax them toward the right location by explaining how and why the answer is in ths manual.

        Teach them to fish as the saying goes.

      • rumba@lemmy.zip
        link
        fedilink
        English
        arrow-up
        4
        ·
        23 hours ago

        Some of them are really well done

        Some of them look like they’re summoning a Great One