131–140 of 179 posts
A heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.
Earlier quoted context omitted.
No, they serve two different purposes. Man pages are a reference/spec on all options and parameters, aimed at those who already have use a tool/technology/concept. This is something different. It's a tutorial of how to do the most common things using that tool. It's a bit like learning a programming language: would you read the formal spec, or would you learn from code examples? Unless you've read formal specs for ot…
There's no reason man pages can't be both. Many man pages contain examples and common usages. See for example the rsync man page, with complete examples of how to backup common file systems.
An examples section in a manpage is a fine idea which I would certainly encourage, but that wouldn't render tldr obsolete.
A heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.
With a man page you know you're getting the right info because it came bundled with the tool.
Shout out to http://cht.sh , which could be used without installing anything: curl cht.sh/tr
Wow that's pretty great. There are so many powerful console utilities with overly opaque manuals that make them hard to jump into when you just want to do a simple thing. Compare these for example: http://cht.sh/jq https://www.systutorials.com/docs/linux/man/1-jq/
Well, man pages cover more than just command-line utilities. These typically go in section 1 only. What about section 2 (system calls) or section 3 (library functions)? I guess the audience of this tool doesn't really need these?
Of course some information will be omitted, that is the entire purpose of this tool. What’s your point?
I would expect such a tool to work so that whenever `man X` produces a long document, searching for X in the tool produces a shortened, example-focused documentation. This is not the case.
Earlier quoted context omitted.
There's no reason man pages can't be both. Many man pages contain examples and common usages. See for example the rsync man page, with complete examples of how to backup common file systems.
One of the nice qualities of man pages is comprehensiveness, while one of the nice qualities of tldr docs is succinctness. Both are mutually exclusive; man pages cannot be both. An examples section in a manpage is a fine idea which I would certainly encourage, but that wouldn't render tldr obsolete.
Earlier quoted context omitted.
Wow that's pretty great. There are so many powerful console utilities with overly opaque manuals that make them hard to jump into when you just want to do a simple thing. Compare these for example: http://cht.sh/jq https://www.systutorials.com/docs/linux/man/1-jq/
The jq manual is very very good.
I would also say though that this cheat sheet looks great as well - cheat sheets absolutely have their place next manuals.
Earlier quoted context omitted.
How is this "rapidly decaying third-party documentation" in any way that man isn't?
man is universally known in the industry, and supported (to some extent, at least) by project authors/maintainers; this project will be forgotten by almost everyone (and start decaying) as soon as this post is off the front page here.
I would be happy to see such a thing taking off. Typical man pages are well, like learning a language by studying a dictionary, alphabetically. It may contain all information, but a clear F on UX. Some packages get slightly better with starting from the most common use cases, with examples (and digestible errors). However, I would be even more interested to see what is the actual usage pattern (e.g. from .bash_histor…
It may contain all information, but a clear F on UX. What I find annoying is the number of command line programs that don't even have man pages anymore. Or maybe that's just an artifact of installing them with brew? What I find interesting is that for the most part (there are exceptions), the older the man page, the more useful it is. Realistic examples. Succinct descriptions. User-friendly terminology. Too many of t…
It's simply a lot harder to explain things in simple language, so I'd hesitate to ascribe such intent.
Earlier quoted context omitted.
I'm not sure what this has to do with Kerrisk. Software maintainers just need to simply add examples of using the software they use. They know best how it works, I don't know why this has to be met with so much friction. Like not posting images of your new game/image library. People want examples of stuff.
I think the hardest part is that people don't know what others don't know. When you're so close to a project, things that are obvious to you are impossible to new people, but you don't realize how impossible it is until you get that feedback.