4 ms·

A suggestion: keep stuff boring. When one is stuck on a problem, maybe with the deadline or angry boss axe pending on her head, last thing she needs is fancy s

A suggestion: keep stuff boring. When one is stuck on a problem, maybe with the deadline or angry boss axe pending on her head, last thing she needs is fancy stuff, emojis, gifa or having to sort through marketing crap (not your case but I've seen plenty of those in "fancy projects") Look at manpages, emergency operation manuals, medical procedures and copy the style Use the website for fancy stuff, it's what's its for Personally the link you shared is perfect to me, at a glance

hutzlibu 6y ago
Ok, but maybe not manpages as a guideline. I seldom find less helpful readme's than manpages. Technical correct, but hard too read with too many details and no simple straight forward example.
- capableweb 6y ago
  Well, I feel like maybe READMEs and manpages have two different goals in mind. READMEs often serve multiple purposes: be a introduction, small tutorial, demos and also reference. While manpages have only one goal, to provide a interface for browsing and reading system reference manuals. So yeah, they are dry, because that's the point. They are supposed to be used as references, not as introductions to a subject.
  - legacynl 6y ago
    > They are supposed to be used as references, not as introductions to a subject. Assuming 'man' is short for 'manual', this is exactly where man-pages go wrong. Especially as a beginner; reading man-pages is a waste of time. It's so dense and obtuse that reading man-pages almost requires reading a man-page on reading man-pages. For example try to figure out how to extract a zip using tar by using the man-pages.
    - hutzlibu 6y ago
      Or simply how to find a file. I gave up and used the file explorer's search function, because I did not wanted to google it. Just a simple example of the most frequent use cases. Thats allmost all I want, together with a listing of the various flags and short, but useful description .
      - tomcooks 6y ago
        If you check at the end of the man page, you'll see that usually an info page is mentioned. Have an online example which illustrates all possible file finding examples you could ever need: https://www.gnu.org/software/findutils/manual/html_mono/find.html https://www.gnu.org/software/findutils/manual/html_mono/find...
        hutzlibu 6y ago
        Thx, but I successfully used find before and know how to google it. That was my point, googling it is much simpler and straightforward than the manpage if you forgot the syntax.
        tomcooks 6y ago
        Indeed, problem is when you don't have internet because your infrastructure is gone and you're the sysadmin. And most importantly, use what you prefer
      - capableweb 6y ago
        Complaining about the manpages for `find` is maybe the worst example you could make, since `find` has surprisingly many examples on its pages. Open the pages and search for `examples` and you'll see what I mean.
        hutzlibu 6y ago
        Sorry I meant locate. But as for find ... are you serious? I said simple example. There are lots of examples, yes, but all do quite complicated stuff (and I had to scroll lots of text to get there). I mean, I can use them, sure, I studied IT. But at that moment, I just wanted to look for one file on all my hd. Not find files with readpermission flag in combination with deleting etc. Imagine a newb. Make things simple. That means you start with the easy things. Like in the case of find, with an example, that looks on a given path for that string. And if I know that, I can work myself up, if I want to. But don't bombard people with information they do not need or want. And if people manage
    - tomcooks 6y ago
      How do you think me and a bunch of *nix beards learned how to survive without Wikipedia, stack overflow, nice IRC volounteers, or functioning search engines? Btw, assuming you meant a gzipped tar, it's tar xvfz (mnemonic: XaVier FugaZi), I can remember from memory solely because of good old RTFM and no hand-holding. Your mileage might vary, but to put it very frankly (and obtusely): if you can't be bothered to learn why should anyone help you, for free?
    - capableweb 6y ago
      > Assuming 'man' is short for 'manual', this is exactly where man-pages go wrong. Why? Manuals come in different levels, not all of them are tutorials/guides, some of them are references. We still call them manuals. > For example try to figure out how to extract a zip using tar by using the man-pages. I'm not sure if you're purposefully mixing tars/zips here, I'm gonna assume you mean a "tar-file" instead of "zip" as obviously tar can't unzip a zip file. Not sure why you're having troubles finding the instructions compared to the thousands of people who managed to find it. Just to refresh my memory (although I know the commands by heart by now), I gave it a try. 1. `man tar` 3. Read through the synopsis, realize I need to specify the archive file with `-f`. 2. Synopsis didn't mention extract, so I search for `extract` as I know I want to extract a file 3. Now I have `tar xf $archive.tar` and I run that. Notice I would like to have some output. 4. Go back to manpages, search for "output" and find the "-v" flag 5. Final command I'm happy with is `tar xfv $archive.tar` Is that really so difficult? Has the internet ruined peoples ability to search for information themselves and playing around?
      - eadler 6y ago
        tar(1) can extract zip files. tar xf file.zip Works perfectly
        capableweb 6y ago
        What tar are you running? I'm running `tar (GNU tar) 1.34` and get a `This does not look like a tar archive` error when trying to extract a zip file.
        eadler 6y ago
        both bsdtar 3.4.3 - libarchive 3.4.3 zlib/1.2.11 liblzma/5.2.5 bz2lib/1.0.8 libzstd/1.4.5 and bsdtar 2.8.3 - libarchive 2.8.3 seem to do the job. I don't use GNU based tools much so I'm unsure if you need special flags for them.
- tomcooks 6y ago
  Manpages give you the precise info you need. Info manuals (mentioned in most manpages, usually triggered by info <command>) are precisely what you're looking for.

hutzlibu 6y ago

Ok, but maybe not manpages as a guideline. I seldom find less helpful readme's than manpages. Technical correct, but hard too read with too many details and no simple straight forward example.

capableweb 6y ago
Well, I feel like maybe READMEs and manpages have two different goals in mind. READMEs often serve multiple purposes: be a introduction, small tutorial, demos and also reference. While manpages have only one goal, to provide a interface for browsing and reading system reference manuals. So yeah, they are dry, because that's the point. They are supposed to be used as references, not as introductions to a subject.
- legacynl 6y ago
  > They are supposed to be used as references, not as introductions to a subject. Assuming 'man' is short for 'manual', this is exactly where man-pages go wrong. Especially as a beginner; reading man-pages is a waste of time. It's so dense and obtuse that reading man-pages almost requires reading a man-page on reading man-pages. For example try to figure out how to extract a zip using tar by using the man-pages.
  - hutzlibu 6y ago
    Or simply how to find a file. I gave up and used the file explorer's search function, because I did not wanted to google it. Just a simple example of the most frequent use cases. Thats allmost all I want, together with a listing of the various flags and short, but useful description .
    - tomcooks 6y ago
      If you check at the end of the man page, you'll see that usually an info page is mentioned. Have an online example which illustrates all possible file finding examples you could ever need: https://www.gnu.org/software/findutils/manual/html_mono/find.html https://www.gnu.org/software/findutils/manual/html_mono/find...
      - hutzlibu 6y ago
        Thx, but I successfully used find before and know how to google it. That was my point, googling it is much simpler and straightforward than the manpage if you forgot the syntax.
        tomcooks 6y ago
        Indeed, problem is when you don't have internet because your infrastructure is gone and you're the sysadmin. And most importantly, use what you prefer
    - capableweb 6y ago
      Complaining about the manpages for `find` is maybe the worst example you could make, since `find` has surprisingly many examples on its pages. Open the pages and search for `examples` and you'll see what I mean.
      - hutzlibu 6y ago
        Sorry I meant locate. But as for find ... are you serious? I said simple example. There are lots of examples, yes, but all do quite complicated stuff (and I had to scroll lots of text to get there). I mean, I can use them, sure, I studied IT. But at that moment, I just wanted to look for one file on all my hd. Not find files with readpermission flag in combination with deleting etc. Imagine a newb. Make things simple. That means you start with the easy things. Like in the case of find, with an example, that looks on a given path for that string. And if I know that, I can work myself up, if I want to. But don't bombard people with information they do not need or want. And if people manage
  - tomcooks 6y ago
    How do you think me and a bunch of *nix beards learned how to survive without Wikipedia, stack overflow, nice IRC volounteers, or functioning search engines? Btw, assuming you meant a gzipped tar, it's tar xvfz (mnemonic: XaVier FugaZi), I can remember from memory solely because of good old RTFM and no hand-holding. Your mileage might vary, but to put it very frankly (and obtusely): if you can't be bothered to learn why should anyone help you, for free?
  - capableweb 6y ago
    > Assuming 'man' is short for 'manual', this is exactly where man-pages go wrong. Why? Manuals come in different levels, not all of them are tutorials/guides, some of them are references. We still call them manuals. > For example try to figure out how to extract a zip using tar by using the man-pages. I'm not sure if you're purposefully mixing tars/zips here, I'm gonna assume you mean a "tar-file" instead of "zip" as obviously tar can't unzip a zip file. Not sure why you're having troubles finding the instructions compared to the thousands of people who managed to find it. Just to refresh my memory (although I know the commands by heart by now), I gave it a try. 1. `man tar` 3. Read through the synopsis, realize I need to specify the archive file with `-f`. 2. Synopsis didn't mention extract, so I search for `extract` as I know I want to extract a file 3. Now I have `tar xf $archive.tar` and I run that. Notice I would like to have some output. 4. Go back to manpages, search for "output" and find the "-v" flag 5. Final command I'm happy with is `tar xfv $archive.tar` Is that really so difficult? Has the internet ruined peoples ability to search for information themselves and playing around?
    - eadler 6y ago
      tar(1) can extract zip files. tar xf file.zip Works perfectly
      - capableweb 6y ago
        What tar are you running? I'm running `tar (GNU tar) 1.34` and get a `This does not look like a tar archive` error when trying to extract a zip file.
        eadler 6y ago
        both bsdtar 3.4.3 - libarchive 3.4.3 zlib/1.2.11 liblzma/5.2.5 bz2lib/1.0.8 libzstd/1.4.5 and bsdtar 2.8.3 - libarchive 2.8.3 seem to do the job. I don't use GNU based tools much so I'm unsure if you need special flags for them.
tomcooks 6y ago
Manpages give you the precise info you need. Info manuals (mentioned in most manpages, usually triggered by info <command>) are precisely what you're looking for.