3 ms·

I like this a lot. ... As a developer who, while (I like to think) competent, hasn't learned to use sed/awk very well .. I find it aggravating and at times ar

by ajkjk 11y ago

I like this a lot. ... As a developer who, while (I like to think) competent, hasn't learned to use sed/awk very well .. I find it aggravating and at times arrogant that long-time users scoff at the idea of replacing them with more general and accessible tools. Why should I have to learn an esoteric syntax with loads of historical baggage and obtuse documentation(1), just because you put up with it? (1) man pages suck, sorry. Good tool documentation starts with basic examples. If I just need to delete a line, search a file, or uncompress a tarball, I should be able to find the simple command in O(1) lines read. ... Case in point, there's a comment here: "Wait: nip 'function(l) { return /^var/.test(l); }' is supposed to be better than egrep '^var' ?" Yes, it absolutely is better (except when performance really matters), because it's very easy to see how to extend that to more complex things, whereas I don't know how to extend egrep without doing lots of reading - if it's even possible without switching tools. And because I can trivially wrap the former in a shell script to produce the latter, more or less. ... I feel this way about a lot of things. I think some people who 'grew up with' certain older technologies end up saying everyone else should use them (which may be true because they're omnipresent) and then extend that logic to say that they're actually good (which is not necessarily and often not true).

hobarrera 11y ago
> Good tool documentation starts with basic examples No. Guides and tutorials do that. Documentations teaches how to use a tool, so you can understand it and fully utilize it. For snippets, bit of working scripts, etc, you have how-to guides, and alike on the internet. The documentation is targeted towards someone wanting to learn about the tool; not somebody who just wants to use it once.
- ajkjk 11y ago
  I disagree. I don't mind if man pages continue to contain all the content they currently have. Just add a section at the top with basic examples and you halve my effort to start using them. That makes them better. Now, if we're picking about the definition of the word 'documentation' - well, I don't care. I just want utility. It's especially better you lower the barrier to entry into the world of command-line-fu. There's a huge class of people in the world who will never, ever touch a command line tool - it's the "non-DevOps" people in the article. Or you can just call them 'non-engineers'. I don't blame these people for avoiding them, either, because ours tools are actively hostile to new users. (in my opinion) The linux community frequently takes a stance of being actively hostile to new users, by intentionally making simple tasks difficult and refusing to provide the most basic of hand-holding. And, of course you can look these things up on the internet, but by that argument we should do away with local man pages entirely. Nah, I'd rather just make the local documentation better.
  - hobarrera 11y ago
    > Just add a section at the top with basic examples and you halve my effort to start using them. That makes them better. Why is moving examples from the bottom to the top better? > There's a huge class of people in the world who will never, ever touch a command line tool So that's your argument in defence of a new command line tool? Oh, the irony. Also, how many of those non-cli users actually know enough programming so as to write raw JavaScript on the cli?
    - ajkjk 11y ago
      Examples at the top is better because experienced users who already know what the tool can do will find what they need regardless of where it's placed, but beginners need to have the barrier to entry lowered. It's not uncommon to open the document, not see what you need, and close it and go looking elsewhere. It's the same reason you put a useful description of your product on its landing page instead of nestled inside subdirectories. I guess I shouldn't have mentioned the people who never touch command-line tools. It's the people who almost-never do who are more convertible. Anyway, there's a marked difference between an easy way to run code on the command line, and a special-purpose tool with special-purpose syntax. Those non-advanced users are the ones who would benefit from having something with easily composable parts. (this is the same argument for building lots of small CLI tools and then composing them together, taken further?) I wager lots of amateur web developers can manage their way around basic JavaScript. It used to be people started coding with shell hacking so they were forced to learn the bizarre tool suite. Now they probably start with web development [citation needed].
Sanddancer 11y ago
One of the big reasons to learn the old fashioned tools is that they're always there. Period. Yes, you have node on your server, and your development machine, but what about when you need to do some work over on the database server? Those antique shell utilities have saved my ass when my more preferred methods weren't available to me. Though the example in question, you're putting in a huge amount of boilerplate code that you're going to have to write a wrapper for with each new script. Most of the basic tools -- sed, grep, awk, even perl -- tend to have a quick and dirty form that does what most people need, with the more powerful portions at the ready. The "new and improved" tools tend to end up a lot like your examples, and get swiftly ignored because it becomes a pain in the ass to type the same thing over and over again, or they grow shortcuts and secrets as time goes on until they too are full of history and shortcuts that only the old timers know. Someone's going to eventually want a patch for a command line flag that wraps all that boilerplate in, and you're going to end up with perl's -n flag, and the horribly ugly code of perl -ne '/^var/ and print' which will confuse beginners, and be a godsend to veterans.
- zimpenfish 11y ago
  > what about when you need to do some work over on the database server? You get the angry DBA coming over with a bat to smack sense into you because You Do Not Work On Servers.

by ajkjk 11y ago

hobarrera 11y ago

> Good tool documentation starts with basic examples No. Guides and tutorials do that. Documentations teaches how to use a tool, so you can understand it and fully utilize it. For snippets, bit of working scripts, etc, you have how-to guides, and alike on the internet. The documentation is targeted towards someone wanting to learn about the tool; not somebody who just wants to use it once.

ajkjk 11y ago
I disagree. I don't mind if man pages continue to contain all the content they currently have. Just add a section at the top with basic examples and you halve my effort to start using them. That makes them better. Now, if we're picking about the definition of the word 'documentation' - well, I don't care. I just want utility. It's especially better you lower the barrier to entry into the world of command-line-fu. There's a huge class of people in the world who will never, ever touch a command line tool - it's the "non-DevOps" people in the article. Or you can just call them 'non-engineers'. I don't blame these people for avoiding them, either, because ours tools are actively hostile to new users. (in my opinion) The linux community frequently takes a stance of being actively hostile to new users, by intentionally making simple tasks difficult and refusing to provide the most basic of hand-holding. And, of course you can look these things up on the internet, but by that argument we should do away with local man pages entirely. Nah, I'd rather just make the local documentation better.
- hobarrera 11y ago
  > Just add a section at the top with basic examples and you halve my effort to start using them. That makes them better. Why is moving examples from the bottom to the top better? > There's a huge class of people in the world who will never, ever touch a command line tool So that's your argument in defence of a new command line tool? Oh, the irony. Also, how many of those non-cli users actually know enough programming so as to write raw JavaScript on the cli?
  - ajkjk 11y ago
    Examples at the top is better because experienced users who already know what the tool can do will find what they need regardless of where it's placed, but beginners need to have the barrier to entry lowered. It's not uncommon to open the document, not see what you need, and close it and go looking elsewhere. It's the same reason you put a useful description of your product on its landing page instead of nestled inside subdirectories. I guess I shouldn't have mentioned the people who never touch command-line tools. It's the people who almost-never do who are more convertible. Anyway, there's a marked difference between an easy way to run code on the command line, and a special-purpose tool with special-purpose syntax. Those non-advanced users are the ones who would benefit from having something with easily composable parts. (this is the same argument for building lots of small CLI tools and then composing them together, taken further?) I wager lots of amateur web developers can manage their way around basic JavaScript. It used to be people started coding with shell hacking so they were forced to learn the bizarre tool suite. Now they probably start with web development [citation needed].

Sanddancer 11y ago

One of the big reasons to learn the old fashioned tools is that they're always there. Period. Yes, you have node on your server, and your development machine, but what about when you need to do some work over on the database server? Those antique shell utilities have saved my ass when my more preferred methods weren't available to me. Though the example in question, you're putting in a huge amount of boilerplate code that you're going to have to write a wrapper for with each new script. Most of the basic tools -- sed, grep, awk, even perl -- tend to have a quick and dirty form that does what most people need, with the more powerful portions at the ready. The "new and improved" tools tend to end up a lot like your examples, and get swiftly ignored because it becomes a pain in the ass to type the same thing over and over again, or they grow shortcuts and secrets as time goes on until they too are full of history and shortcuts that only the old timers know. Someone's going to eventually want a patch for a command line flag that wraps all that boilerplate in, and you're going to end up with perl's -n flag, and the horribly ugly code of perl -ne '/^var/ and print' which will confuse beginners, and be a godsend to veterans.

zimpenfish 11y ago
> what about when you need to do some work over on the database server? You get the angry DBA coming over with a bat to smack sense into you because You Do Not Work On Servers.