7 ms·
Frankly I've never liked man pages. To me they always screamed "This is how documentation was done in the 90s." The examples are often very unclear or incomplet
by aerovistae 10y ago
Frankly I've never liked man pages. To me they always screamed "This is how documentation was done in the 90s." The examples are often very unclear or incomplete, and the explanations often assume prior knowledge without providing links in case such knowledge is absent.
Modern documentation has gotten way better, as seen in the Stripe docs and many others, and I wish the man pages could be updated accordingly.
- microcolonel 10y agoThe quality of manpages can vary significantly, however many of them are excellent. The Git manpages stand out; most of the system manpages for OpenBSD are excellent as well. One other nice thing is integration with an editor. I view manpages in emacs, and can yank the snippets directly into my other buffers for extra convenience.
- beachstartup 10y agoi use the curl and rsync man pages weekly, if not daily for a stretch, and they're great.
- geggam 10y agoWhat is your better solution ? Instead of being derogatory about a technology which works how about creating your ideal and seeing if the Internet likes it ?
- headShrinker 10y agoIt's a good ideal but it also helps to recognize the problem. Not everyone that recognizes the problem is apt or interested in offering a solution. Also I don't believe parent comment was intended to be derogatory
- aerovistae 10y agoIndeed. When you do user testing and they tell you a certain component of your application is confusing or hard-to-use, do you castigate them for being derogatory and tell them to fix it?
- krirken 10y agoIf not derogatory, I have never found the "This is how ... was done in the 90s/80s/70s" sentiment to contribute much to a conversation.
- spyrosg 10y agoI don't know. I really like the moments where Alan Kay appears out of nowhere, tells where your idea squanders the potential of computers, points to 60's-80's prior art that did it better anyway, and disappears in a puff of smoke. The last thing our discipline needs is us thinking we got it all and it just needs polishing.
- aerovistae 10y agoI understand what you're saying but I think it goes without saying that we've started paying more attention to quality of user experience for software in the past twenty years. If you genuinely disagree and believe the 90s were as ripe with quality tooling and documentation as 2016, well, that's a bit strange, but you're certainly entitled to your opinion.
- dingaling 10y agoYes man pages are usually upside-down; the examples should be right at the start and then lead to a drill-down into options. 9/10 times I end-up having to search the web for a basic introductory example. But even in big corps corps with ISO9000 accreditation there is seldom self- questioning as to whether documentation is useful rather than just ticking the box for process-completeness.
- mrspeaker 10y agoYes! For some reason I still always type `man whatever` when I need to do something with a tool... even though I'm just presented with 50 pages of gibberish that I scroll through for a few pages then go to Stack Overflow. The problem I usually find is that man pages give equal importance to every possible flag - making really hard to figure out which elements you most likely will need to do common tasks.
- ktRolster 10y agoWhoever answers your question on Stack Overflow likely got their information from a man page.
- ori_b 10y agoNo. 90% of the time, I know what I want to do, and how my tools work. I just don't remember the options are called. Having a summary of the options right there at the top is the most valuable thing in a reference.
- gpvos 10y agoFor that there is the --help option.
- bluejekyll 10y agoAnd for this implementing cli, I've found http://docopt.org http://docopt.org to be an excellent and simple way to provide standard options and docs easily.
- gkya 10y agoThe quality of the medium is not determined by the quality of its content. GNU manpages especially are incredibly low quality (they have info(1) for extensive documentation), but not all man pages are GNU manpages. If you use man with shell job control (Ctrl-z, fg, bg), you can easily read multiple man pages simultaneously.
- Nullabillity 10y agoAt least man pages don't break your scrolling.
- taeric 10y agoAnd, for myself, I couldn't disagree more. Man pages are very well done, since they are more often used for reference than they are for discovery. Similarly, documentation seems to have apexed with the TeXbook. :(