A few years ago, some of our clients had complained that the Syzygy Automation Suite manuals were too "sparse" and needed more information and examples. The manuals at that time were about 90+ pages long for each part of the automation suite. So, we revamped everything and added more information (a lot of it) and several examples for each possible command, and even some screen shots of things in action and a new "hints and tips" section. The users loved it. This made the average size of our users guide for each of the products in the 350+ page range.
Just this week, when we shipped a new version of a part of our Automation suite, SyzMPF/z (the console message automation part), with many new features and with it's new 398 page manual, we actually received several complaints that first day that the manual was "too large" to print. We deliver it in Word or PDF format (their choice), and apparently they are upset because it takes close to a ream of paper to print just the one manual. These are basically reference manuals and are formatted so that you can use them well without printing with cross references and links to other parts of the manual and even to other manuals (which are pretty useless if you print them), but I guess some people still want to feel the paper. They have asked us to "streamline" the manual "like the old days" and remove the extra "fluff" of examples, they complain that our descriptions of the commands don't need to break out each and every parm and sub-paramter. We have been asked to cut the books by "at least" 50%. We think the parms do need to be broken out for every command because you can't assume that the sub-parms always have exactly the same meaning and use. And you can't assume that someone will have seen things in some other section and will apply that knowledge to the section with the command that they are looking into. That was the problem we had with the old manuals, we assumed that they would read the whole thing. But at 398 pages, we pretty much KNOW that they won't read the whole thing so we made sure that every parm and sub=parm was listed for every command. Anyway, I'm sure that other vendors have received these same kinds of complaints and it's probably why they end up reducing the content in their manuals. Possibly the users complain loudly about what they see, and only slightly about what they don't see. We are still actively in the process of adding to the manuals, and this one will likely be broken into two separate manuals, but having two just under 300 page manuals (because of the overlap) instead of one almost 400 page manual doesn't really seem like it's going to resolve this issue. But that's what will likely happen. Brian ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to [email protected] with the message: INFO IBM-MAIN
