1. 14
  1.  

  2. 6

    What isn’t community driven about man pages? Do man page authors not accept patches?

    1. 3

      Having it on Github does make it easier for many people to contribute - the process to submit a patch to man-pages on linux involves emailing the patch to the mailing list using the correct patch format, which can be tricky to figure out.

      It does worry me that Github is such a central place for open source projects, given that it’s closed source, but they do have a far, far easier interface for contribution than most of the kernel.org projects.

      That being said, I don’t think that something like TLDR pages are a good solution to the lack of good documentation. It seems like it’ll duplicate a lot of work that’s already been done, and I’d have a hard time trusting it until it has much more of a track record. I’d also be concerned about a project like this getting out of date quickly. Personally, I think that more useful avenues of contribution would be contributing more examples to the linux/etc man-pages project, and contributing directly to the documentation of programs that are not included in the generic man-pages project.

      While this is an interesting project, and I’m glad that people are working on improving docs, fragmentation and stale information is a pretty big concern with documentation, which makes me wary of projects like this.

      1. 1

        This is easier to approach, just fork on Github and everyone will npm install your contribution. Or something.

        Better documentation is always welcome, but there’s this strange aura of laziness around this I can’t really put my finger on. Maybe because there are so many clients?

      2. 3

        I agree with the need for vastly better documentation everywhere. Both better summaries and examples, but also more precise terms being careful to describe edge cases with detail. One of my favourite examples are the pages describing DJB daemontools: https://cr.yp.to/daemontools/svscan.html, notice how short, yet detailed the are, even describing system limits.

        Just a thought, I didn’t like the home page tar example on the linked page because it requires the reader to infer the meaning of the letters, here is how I would have presented it (if the formatting holds).

        tar  c         z                   f         foo.tar.gz dir
             ^ create  ^ with compression  ^ a file  ^ called   ^ from this source
        
        1. 2

          When I tried to relearn GPG with man pages, the interface was as horrible as I remember or worse. I found the GPG Cheat Sheet that showed examples of common uses.

          http://irtfweb.ifa.hawaii.edu/~lockhart/gpg/

          Clean-looking and simple. Still had to validate the ones I was using against the man pages to spot any BS but definitely a time saver. Why couldn’t all man pages have at least one section with similarly nice-looking stuff? TLDR pages look close to that concept. Neat project. Hope it or something similar gets popular.

          1. 3

            Man pages are usually nice references when you know what you want and just need to find the names of the correct flags. Learning a program by reading the man page feels a bit like learning a language by reading the dictionary.

            TLDR pages look really neat indeed.

            1. 1

              Them as a reference only is a good counterpoint. Some could be intended that way. Gotta wonder, though, with how many time veterans tell new people in various places they shouldve just read the man pages.

              1. 6

                openbsd is the only large software project I have seen where the man pages are the primary reference. Because of this, googling openbsd doesn’t seem to show much, but once learn to use the man pages, you find perhaps one reason it isn’t explained in forums, is because the primary source had the info to begin with (another reason might just be popularity).

                With linux and mac, the information seems to be so scattered that the best source is always a google search of someone who had been puzzled, though you must always check the date of the post and guess whether or not the info is still good.

            2. 2

              Man pages are actually supposed to have a section called EXAMPLE or EXAMPLES near the end, as specified by the Linux man-pages project and OpenBSD.

              I presume it’s supposed to be one of the last sections so that you get there immediately when you press G/End. The quality of the examples may vary wildly for command-line utilities, though. gpg(1) puts a number of other things in the way of its EXAMPLES section, which makes it a bit less convenient.