11–20 of 50 posts
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.
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.
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.
Having a summary of the options right there at the top is the most valuable thing in a reference.
Earlier 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
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.
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.
I'm curious how much of this still stands today.
"Experts"... lol...
The experts writting it for themselves part seemed inaccurate given what I read in LibreSSL commits. It was one atrocity after another. Still love Ted Unganst's observation about them making surd endianess of CPU doesnt change while protocol is running. Just cant remember how often that check was performed. "Experts"... lol...
Earlier quoted context omitted.
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
If not derogatory, I have never found the "This is how ... was done in the 90s/80s/70s" sentiment to contribute much to a conversation.
The last thing our discipline needs is us thinking we got it all and it just needs polishing.
Earlier quoted context omitted.
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
If not derogatory, I have never found the "This is how ... was done in the 90s/80s/70s" sentiment to contribute much to a conversation.
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.
Earlier quoted context omitted.
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.
No. 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.