3 ms·

> 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 f

> 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].

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].