Just how bad is OpenSSL? (2012)
lists.randombit.net
Just how bad is OpenSSL? (2012)
1–10 of 50 posts
Re: Just how bad is OpenSSL? (2012)
#2Frankly 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.
Re: Just how bad is OpenSSL? (2012)
#3Frankly 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.
The 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.
Re: Just how bad is OpenSSL? (2012)
#4Frankly 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.
What 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 ?
Re: Just how bad is OpenSSL? (2012)
#5Frankly 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.
The 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.
i use the curl and rsync man pages weekly, if not daily for a stretch, and they're great.
Re: Just how bad is OpenSSL? (2012)
#6Frankly 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.
Yes 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.
Re: Just how bad is OpenSSL? (2012)
#7Frankly 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.
What 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 ?
It'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
Re: Just how bad is OpenSSL? (2012)
#8Frankly 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.
The 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.
Re: Just how bad is OpenSSL? (2012)
#9Frankly 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.
Yes 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.
Yes! 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.
Re: Just how bad is OpenSSL? (2012)
#10Earlier quoted context omitted.
What 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 ?
It'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
Indeed. 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?