The wisdom of the crowd is great, but the crowd is best at knowing things not discoverable by other means. The crowd does a comparatively worse job reading the documentation.
I hypothesize the following cause: experts read documentation and don’t write blog posts about it. They blog about things that are hard. The people who blog about documented aspects are non experts. Their efforts to simplify the documentation may omit important information.
There was also this amazing insight from Ingo I forgot to include in the post. I think he is spot on. The current state of expecting people to find the documentation online is the big problem.
I was of course trigger happy with the post omitting feedback and trigger happy with the devel/zeal port to cause Ingo to write it up :) I am happy he did though :)
A bit of food for thought: if people are now used to google for documentation, are they “wrong” or is it us who are “wrong” for wanting to keep it bundled with the software as it should be expected?
I mean, in the end, I feel that us developers should provide people what they want, and not force them to use what we think (and may actually be) right and proper.
I love OpenBSD’s approach, but then, OpenBSD is not a mainstream product and thus it can’t be used as a reference when discussing this topic. It does really suit the needs of its users.
However, for some, let’s say, phone game, or mainstream software product like MS Office, shouldn’t it behave as its users expect it to, not the other way around?
OK. Let’s bring it all together. :) Yesterday somebody posted this comment to HN about tar (yes, tar again) command line arguments and having to google it every time.
Why google? You’re already in a shell about to run tar. Just run man tar.
The first reply is wrong. -c is not compress, it’s create.
The next reply is also wrong, as far as OpenBSD goes. OpenBSD tar doesn’t sniff the file header.
In conclusion, reading the local documentation on your system is 1) readily accessible, 2), correct, and 3) pertinent to the system you are running.
As for Office, I think large software suites are a slightly different animal, but at least in the past Office came with pretty thorough help. Microsoft spends more effort on documentation than any other company I know.
I don’t know where I’d be without ‘man’, but I do tend to avoid info pages. The ‘pinfo’ tool is a somewhat more useful infopage browser, but in general whenever a man page refers to some info page, I run off, feeling like I just unintentionally played doorbell ditch!
Info makes me run screaming too. In my experience they have been a bewildering confusion of links, not dissimilar to wikis, where every page seems to hint that if you just follow one more link you might find your answer. I avoid them.
Their efforts to simplify the documentation may omit important information.
There was a blog post recently (perhaps by you?) talking about a man page that had gotten simplified and had removed a note about the interpretation of the digit on a file descriptor.
The subtle (and easily overlooked) original blurb in the docs hinted that there would be only FDs 0-9 (because the docs said digit instead of digits). When well-meaning folks streamlined the docs, the behavior was completely omitted and hilarity ensued.
Manuals definitely have their shortcomings. At least when presented as man pages. 100 years ago when they were printed out this was probably easier.
For instance, if you have a cluster of OpenBSD machines and you want to consolidate authentication, it’s a long road to discover that you want YP and how to set it up. And honestly, you probably want to use ldap with the YP bridge. But “man cluster” doesn’t do much to point you in this direction.
We have man pages for tools and functions. But less so for concepts and advice.
A good question. It’s a matter of where to put and what to call it. Some man pages do have examples. For instance, it’s hard to learn socket programming from the socket and connect man pages. But there’s a nice example at the bottom of getaddrinfo which I always copy from. The hard part is knowing it’s there.
On the OpenBSD side, there’s also an attitude that too many examples are bad. Users should have to think about what they’re doing, not just copy examples. That doesn’t always give the best result. At some point, users only look at the examples and then anything you don’t provide an example for becomes impossible.
I don’t know about arch, but I spent some time reading various ubuntu wikis trying to set up postfix one time. All in all, it seemed to be guiding me for a much more complicated setup than I wanted, but that’s because the author felt a good mail server should be set up that way. I suspect some wiki/howto authors get a little carried away and embellish the setup to show off.
It wasn’t maintained and eventually became misleading outdated cruft.
Updating reference documentation like man pages is less work for developers than keeping walk-through tutorial-style docs up to date.
Who actually goes back and updates their old blog posts which are providing outdated advice? Same problem.
I’m not saying this is a good situation. I had to read 4 blog posts and one slide deck, of various vintage, until I had a clear picture of how to set up L2TP/IPsec on OpenBSD. But the effort involved in maintaining such docs cannot be underestimated either.
I only use search results to get a hint about what strategies exist, and then actually go read the documentation for those strategies. It’s a nice compromise of fast and thorough.
Also I use dash, which makes docs trivially searchable for tons of languages and libraries. I think dash is what actually made me start searching less: it became tedious to even wait for a network round trip to get access to what I needed. Brilliant tool, best $20 I ever spent.
I searched the web and some mailing lists yesterday to find out how to set up an OpenBSD L2TP/IPsec server for my android phone. Don’t think I would have managed without.
The wisdom of the crowd is great, but the crowd is best at knowing things not discoverable by other means. The crowd does a comparatively worse job reading the documentation.
I hypothesize the following cause: experts read documentation and don’t write blog posts about it. They blog about things that are hard. The people who blog about documented aspects are non experts. Their efforts to simplify the documentation may omit important information.
There was also this amazing insight from Ingo I forgot to include in the post. I think he is spot on. The current state of expecting people to find the documentation online is the big problem.
I was of course trigger happy with the post omitting feedback and trigger happy with the devel/zeal port to cause Ingo to write it up :) I am happy he did though :)
A bit of food for thought: if people are now used to google for documentation, are they “wrong” or is it us who are “wrong” for wanting to keep it bundled with the software as it should be expected?
I mean, in the end, I feel that us developers should provide people what they want, and not force them to use what we think (and may actually be) right and proper.
I love OpenBSD’s approach, but then, OpenBSD is not a mainstream product and thus it can’t be used as a reference when discussing this topic. It does really suit the needs of its users.
However, for some, let’s say, phone game, or mainstream software product like MS Office, shouldn’t it behave as its users expect it to, not the other way around?
OK. Let’s bring it all together. :) Yesterday somebody posted this comment to HN about tar (yes, tar again) command line arguments and having to google it every time.
Why google? You’re already in a shell about to run tar. Just run man tar.
The first reply is wrong. -c is not compress, it’s create.
The next reply is also wrong, as far as OpenBSD goes. OpenBSD tar doesn’t sniff the file header.
In conclusion, reading the local documentation on your system is 1) readily accessible, 2), correct, and 3) pertinent to the system you are running.
As for Office, I think large software suites are a slightly different animal, but at least in the past Office came with pretty thorough help. Microsoft spends more effort on documentation than any other company I know.
I don’t know where I’d be without ‘man’, but I do tend to avoid info pages. The ‘pinfo’ tool is a somewhat more useful infopage browser, but in general whenever a man page refers to some info page, I run off, feeling like I just unintentionally played doorbell ditch!
Info makes me run screaming too. In my experience they have been a bewildering confusion of links, not dissimilar to wikis, where every page seems to hint that if you just follow one more link you might find your answer. I avoid them.
There was a blog post recently (perhaps by you?) talking about a man page that had gotten simplified and had removed a note about the interpretation of the digit on a file descriptor.
The subtle (and easily overlooked) original blurb in the docs hinted that there would be only FDs 0-9 (because the docs said digit instead of digits). When well-meaning folks streamlined the docs, the behavior was completely omitted and hilarity ensued.
[Comment removed by author]
Manuals definitely have their shortcomings. At least when presented as man pages. 100 years ago when they were printed out this was probably easier.
For instance, if you have a cluster of OpenBSD machines and you want to consolidate authentication, it’s a long road to discover that you want YP and how to set it up. And honestly, you probably want to use ldap with the YP bridge. But “man cluster” doesn’t do much to point you in this direction.
We have man pages for tools and functions. But less so for concepts and advice.
This is going to be a naive question, but why can’t we make another manpage section exactly for that? And slowly but steady fill it?
Arch Linux does have something akin to that: you can have all the wikified knowledge with http://kmkeen.com/arch-wiki-lite/
A good question. It’s a matter of where to put and what to call it. Some man pages do have examples. For instance, it’s hard to learn socket programming from the socket and connect man pages. But there’s a nice example at the bottom of getaddrinfo which I always copy from. The hard part is knowing it’s there.
On the OpenBSD side, there’s also an attitude that too many examples are bad. Users should have to think about what they’re doing, not just copy examples. That doesn’t always give the best result. At some point, users only look at the examples and then anything you don’t provide an example for becomes impossible.
I don’t know about arch, but I spent some time reading various ubuntu wikis trying to set up postfix one time. All in all, it seemed to be guiding me for a much more complicated setup than I wanted, but that’s because the author felt a good mail server should be set up that way. I suspect some wiki/howto authors get a little carried away and embellish the setup to show off.
/usr/src/share/docUser’s Supplementary Documentation, Programmer’s Supplementary Documentation, System Manager’s Manual.
That did actually exist at some point: http://cvsweb.openbsd.org/cgi-bin/cvsweb/src/share/doc/
It wasn’t maintained and eventually became misleading outdated cruft.
Updating reference documentation like man pages is less work for developers than keeping walk-through tutorial-style docs up to date. Who actually goes back and updates their old blog posts which are providing outdated advice? Same problem.
I’m not saying this is a good situation. I had to read 4 blog posts and one slide deck, of various vintage, until I had a clear picture of how to set up L2TP/IPsec on OpenBSD. But the effort involved in maintaining such docs cannot be underestimated either.
I only use search results to get a hint about what strategies exist, and then actually go read the documentation for those strategies. It’s a nice compromise of fast and thorough.
Also I use dash, which makes docs trivially searchable for tons of languages and libraries. I think dash is what actually made me start searching less: it became tedious to even wait for a network round trip to get access to what I needed. Brilliant tool, best $20 I ever spent.
I searched the web and some mailing lists yesterday to find out how to set up an OpenBSD L2TP/IPsec server for my android phone. Don’t think I would have managed without.