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 <[EMAIL PROTECTED]>, 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/
_______________________________________________
use-revolution mailing list
[EMAIL PROTECTED]
http://lists.runrev.com/mailman/listinfo/use-revolution
