Apparently people want task-oriented documentation that helps them be at least somewhat productive quickly. I guess I can understand that. People want to get work done _now_, and want to get paid _now_ too. But I would hope it would include plenty of links to additional resources (in depth documentation, training, external sources, ...) to encourage them to go beyond routine and repetitive activities and get on with developing advanced skills.
Right now there seems to often be a disconnect between sleep-inducing task documentation, and opaque reference documentation. I think in addition to links, examples might make the former more interesting, and a introductory document on how to understand the reference documentation (for example, for man pages, a more friendly single document that covered the high points of the various Intro([14-7]*) pages, man(5) without the troff specifics, attributes(5), and so on) might make the latter more accessible. And I would hope that task-oriented documentation would actually be tested on people that were no more specifically familiar with the material than the intended audience was expected to be. As such, the documentation itself should include an invitation for feedback. And it might be useful to attempt to describe the approximate limitations of that sort of documentation, too. This message posted from opensolaris.org
