Julia EvansFeb 20

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ā€™d look there first
57.6%
Only after trying other options first
33.2%
Never
6.4%
Other / not sure
2.8%
Poll ended at .
Show threadJulia EvansFeb 20

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")

Show threadJulia EvansFeb 20
i think part of the reason I'm feeling interested in man pages right now even though I rarely use them is that search has gotten so much worse, it's frustrating, and it makes it feel more appealing to have trustworthy sources with clear explanations
Show threadRyanParsley

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

Feb 20 at 2:42pmMastodon for Android
Show threadJulia EvansFeb 20
@RyanParsley to be clear for me i'm mostly interested in figuring out if the man pages can become _better_ so that using them is actually a good experience, not accepting a bad experience
Show threadRyanParsleyFeb 20

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

Show threadRyanParsleyFeb 20
@b0rk when you say better, do you mean content or format? Like jq man page is pretty stellar on the content side.
Show threadJulia EvansFeb 20

@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)

Show threadRyanParsleyFeb 20

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

tldr pages

Simplified and community-driven man pages

Show threadJulia EvansFeb 20
@RyanParsley yeah! i think 20 people have told me about it today haha, I don't use it either but people tell me all the time that they like it, I think it's an interesting project
Show threadMattias WadmanFeb 20
@b0rk @RyanParsley any idea what are the main pain points make it hard to learn? "everything is a generator" and how arguments work are two of them it seems
Show threadJulia EvansFeb 20
@wader not sure, maybe the idea of learning a specialized domain specific language just doesn't feel worth it. Like I've never learned the awk language either
Show threadMattias WadmanFeb 20
@b0rk that makes sense, and same for me about awk, maybe because jq fills that gap for most of my needs. but it you ever need to do lots of adhoc query and transform of semi-structured data i can recommend to learn jq!
Show threadJulia EvansFeb 20
@wader been trying out fx recently and I think it might work bette for mer, we'll see https://cheat.sh/
cheat.sh/:firstpage

Show threadMattias WadmanFeb 20
@b0rk šŸ‘ good to hear, only used it briefly. happy to answer jq questions if you ever venture into it again
Show threadJulia EvansFeb 20
@wader thanks so much!
Show threadRyanParsleyFeb 20

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