standalone has plainly readable transcript

[Victor Eijkhout]

>As a documentation professional,

Hmmm.... Amateur with delusions of grandeur? (Actually, on my private 
web page you find my main claim to fame.)

>surely you recognize the dynamic that
>occurs once the meme of "the docs are inadequate" grows legs:

Yeah. Point taken, and apologies for the overly broad generalisation.

>Given your experience, what specific remedies would you
>recommend?

I haven't started working with version 2 yet, so with the proviso 
that I haven't seen the updated docs: I think a lot of complicated 
systems are complicated partly because of the interactions between 
the parts, not the number of parts or any intrinsic property of them 
as such. Thus I favour a style of explanation where the explanation 
by command/keyword or even by category is secondary to one by topic. 
As an alternative to "topic", think "environment", taking that word 
fairly in the abstract. An environment is only partly a distinct part 
of the system, it is also a mode of working, or a set of common 
idioms to work with. Identifying these topics/environments is a good 
way to bring together conceptually related commands and keywords.

Remember the "I should have made the connection" comment that 
triggered my initial post? I think the big advantage to this approach 
is that you make a number of these connections for the reader. 
Instead of emphasis on desrcribing commands and keywords you get an 
emphasis on describing common "idioms", ready-made connections 
between the commands and keywords. Of course you can't give all 
possible connections in a manual, but giving a number of them gives 
the reader a more operative definition, rather than a dictionary 
definition.

Anyway, that's my opinion as only a some-time tech writer. (Check out 
http://www.eijkhout.net/tbt for my credentials.)
-- 
Victor Eijkhout <eijkhout at cs.utk.edu>, 329 Claxton, Comp Sci, UT, 
Knoxville TN 37996.
tel: 865 974 9308 (W), 865 673 6998 (H), 865 974 8296 (F)
http://www.cs.utk.edu/~eijkhout/