when do you usually use the man page for a complex command line tool to answer a question you have? (like git, openssl, rsync, curl, etc)
(edit: no need to say "i use --help then man")
i'm very curious about everyone who says "I'd look there first", if I want to figure out how to do something new I think I'll usually google how to do it rather than look at the man page, and then maybe later look at the man page to look up the details
(I've gotten enough of these answers:
- "I like that man pages don't require changing context"
- "with the man page I know I have the right version of the docs")
@b0rk I date from the days when man pages were a novelty.
If it doesn't have a man page, it isn't finished.
@b0rk One thing, and I don't know that this is solveable or maybe it was supposed to be solved by info pages but those were hard to memorize how to use, is learning the capabilities of a tool like...up front and at the top.
It's so hard to find the ingredients I need to concoct the correct incantation from man pages, even when I've done the thing with the tool before.
And sometimes you find things that SEEM like what you need but aren't.
@b0rk I have a lingering guilt about not going to man pages first, but often a blog post has been better crafted than the friendly manual. Not all manuals but enough to encourage an antipattern in search first.
I totally agree with your motivation to address/revaluate that.
@b0rk a general statement of when official docs feel not super helpful is when they clearly articulate what a tool does without managing to express why/when kinds of context.
A good blog post about a tool tells a story that docs don't tend to.
Why does `man stow` mention perl or Carnegie mellon's depo program? That man page is pretty good all around but does have stuff to skim over that doesn't feel like it's there in service of the user.
@RyanParsley either!
(it's a little hard for me to think about jq because I've completely given up on learning the jq language, but I don't think that has anything to do with the quality of the documentation)
@b0rk are you already familiar with https://tldr.sh/. I don't have it in my workflow, but seems like a neat idea to complement man pages.
Even if you have no interest in using it, perhaps it's existence and what's working there could be useful data.
@b0rk the man page for just is basically a less pretty help command :)
I suspect if people discover too many in a row like that and stop running that command.
@b0rk i remember this: when i learned about man and started using it, the stuff i wanted to know usually was on page 5 (quick reference / parameters). But i always forget that so it felt frustrating and abandoned them.
Instead I use --help command options. I only go to man when i want to learn the full and long version. But sometimes I do.
@b0rk I'm the kind of person who enjoyed reading man pages for leisure.
I read through the entirety of the rsync man page to compose my own favourite rsync invocation once.
The only tools where I resort to web search are shells, because their man pages are really hard to navigate (finding documentation for `read` in the bash man page is ... a nightmare).
Web search is often imprecise and as you note, has gotten so much worse that I am glad I never fully relied on it.
@b0rk For me, it is avery very old habit. When I started out poking at Unix systems, if I wanted to "get information from outside the computer I was on", I could, if I was lucky, turn my head and ask someone else in the same room.
Otherwise, I would have to fire up a newsreader, post to UseNet, wait for the UUCP spool to empty (over a modem), wait for the reply to be written, then wait for the relevant article to trickle back in a later UUCP update batch.
I will, frequently, after having opened the man page, start a web search pretty soon after, because many man pages are badly written (and I must say that good technical writing is a skill that doesn't necessarily correlate with "ability to write code").
@b0rk It depends. I use Google first when I try to find the right tool for the job, and those searches usually yield full commands that I can just copy-paste. But a manpage in this case won't help as I don't know what to man.
When I know the right tool, and it's not ffmpeg, I try to craft the correct command myself. That helps me remember it better.
@b0rk for me, I think it's a combination of an 'old people' thing and a 'highly suspicious of a lot of the modern Internet' thing.
When I learned to use computers, competent search engines and rich online resources like Stack Exchange were a long way off – even having the Internet in your home without paying per minute wasn't around yet. So you had to develop the skills of finding stuff out from the available local resources like manuals, because that was all you had.
Then good search engines came along, but I was always aware that there's a risk of depending too much on them and losing the ability to figure stuff out yourself. Even now, I sometimes find myself coding without the Internet (or effectively so – laptop on train with terrible connectivity) and it's useful that I can still get things done.
And now search engines are all getting enshittified, and/or monetised, and/or straight-up _worse_ (Google doesn't return the results I actually wanted nearly as often as it used to). And the less said about 2020s answers to this kind of question, the better. So I'm doubly glad I haven't abandoned my old approaches to things. More and more I feel it's important to keep external corporately-provided "do it for you" services at arm's length, and not base your whole workflow on them to the extent that you're a captive market or dependent on them not going down.
@b0rk @simontatham You've DEFINITELY given me something to think about.
In rsync's case in particular, I go to the HTML version of the man page on Samba's website and look it up there. I think if the man page was easier to invoke outside of a terminal window with browser/editor bindings (read: CTRL+F), I train my brain to use the local copy.
@cr1901 @b0rk @simontatham for certain tools that have a capital-M Manual—you know, the organized kind that you'd get an HTML or PDF render of—you'll sometimes find the HTML packaged in Linux distros (as a separate -doc subpackage if not in the main package itself). but to open such docs, you'll have to root around in /usr/share{,doc}, and that's if you know the manual exists in the first place; you might just as well find a bare-minimum README...
seems like there's an unfilled niche for making a system's heterogenous doc tree more discoverable. something with slightly more tailored UI than a directory tree view (let alone navigating to each one individually). a generated HTML page would be a good start, and a plugin for KHelpCenter and such would be really cool. it's entirely possible there's an existing solution here I'm just not familiar with, though
@rudi @b0rk yes, programming languages that have a strong culture of good docs are definitely a plus.
Still on the subject of decoupling myself from Internet dependence, I've been working hard on my Rust workflows recently so that I more often use local `cargo doc` or `rustup doc` instead of just going to docs.rs/foo or doc.rust-lang.org/bar. Partly that means I can still consult the docs if the Internet is out of reach, and partly it means I get the version of the docs that matches what I'm actually using.
("Working hard" in the sense that first I had to fix some annoying problems that meant those commands didn't even work for me, like Ubuntu wanted to open the rustdoc output in Abiword, or rustup put its docs somewhere that the apparmor restrictions on snap!Firefox didn't let it read.)
@b0rk answered with that option as well. with alt+h in fish, it just opens as some kind of overlay, allowing me to search the man page without removing what I've entered first.
If the man page doesn't work, the second approach is `cheat <command>` with cheat being a fish function which queries cheat.sh/<command> and pipes the output into bat.
And only after that, I'll search for information via the browser ^^
@b0rk It was a bit of a toss-up for me. Sometimes I'll go straight to man, other times straight to generic google alternative. Man has the advantage of being right there - I don't even have to change my window focus - and while it can be very dense, there's a good chance I'll find an answer in the introduction or the examples at the end. But often it's simply too dense and I'm more interested in quickly solving the problem right in front of me than mastering a new tool, and then I'll open a browser and do a search.
The bad news for man pages though is that quality has definitely declined over the years. More modern packages are less likely to have a good man page, or sometimes don't have one at all. It's pretty obvious why, no sense complaining about it, but it can be annoying.
@uastronomer when you say "it's pretty obvious why" what do you mean?
(is it that with stack overflow & the internet generally it feels like there's less pressure to have good docs than when they were the only source of information?)
@b0rk Hmm. Not so obvious after all, now that you've made me think about it.
I mean that dev teams don't always have the resources or interest in supporting what they might see as "legacy" documentation, especially when they are already expected to put documentation on their website, in github, on discord, or wherever else their community hangs out. This wasn't an option in the old days, but now it is.
@b0rk It kind of depends on the question—usually my question is something like “what's the option to do such-and-such again?” which is easily answered by --help or the manpage.
When it's something more conceptual, then --help probably won't explain it and my first stop will be the manpage to see whether it does, because it's authoritative and I already have it. If that fails, then I'll try the web, and maybe a relevant book if I have one.
@b0rk I search for tools where I already know the man page is unhelpful (either too small or there's just a million options that make a whole language to learn to do basic stuff).
Which is quite a lot tbh, but I do absolutely start out with the official documentation on practically everything. Answers and mistake-preventions are almost always found in there the quickest, because mistakes consume a ton of time.
Julia Evans
John Maxwell
Master Squinter
excited for the mastodon rise
Minkiu
Jerome (He/Him)
RyanParsley
Mattias Wadman
r-hold
Sandzwerg
Jonas Schäfer
Damien Sorresso
Chase
Benjamin Geer
Stéphane Bortzmeyer
dave
Matt Panaro
Phil
Wenzel Massag
Richard "mtfnpy" Harman (he/him)
Russell Davis
Ingvar
Mx. Eddie R
Sebastian Hagedorn 
joe aka Minami-o
Karl
Simon Tatham
dakkar
Arturo Serrano 🇨🇴🤖👽🧙🦄
William D. Jones
Will 💜
rudi
Unix Herder
Gaëtan Duchaussois
hundesohn, seine schwester
Allen but one of the good ones
PolyWolf
chupson
Peter Hosey
Astrid
groxx
Stewart Russell