Let’s bring the Boulder Library into the discussion. It worked, it was accurate, the search engine was the best I’ve ever seen.
On Wed, Oct 22, 2025 at 11:06 AM Steve Thompson <[email protected]> wrote: > At various SHARE conferences I was able to attend, and other > places of meeting, it has been discussed that IBM management > makes decisions about documentation wherein they have zero input > from the actual users. And since management of companies using > IBM doc doesn't see the problems it causes their own people, > nothing ever gets said and so cost cutting rules. > > However, in most ISV shops I've had the pleasure to work in, we > tended to listen to those that called about problems (sysprogs, > admins, etc.) and fixed our doc accordingly (similar to what > Brian Westerman said below) > > So it seems that with IBM, cost cutting is the driving force for > getting performance bonus... > > Regards, > Steve Thompson > > On 10/22/2025 3:28 AM, Colin Paice wrote: > > I worked on a large IBM product. We had an API reference and a user's > > guide. The reference was all the APIs and options. The user's guide > > gave examples - and softcopy links to the topics in the reference. > > We also had a command reference, and a planning guide which gave > pre-reqs, > > and examples of typical configurations - including the commands needed to > > create them. In effect, it was a command user's guide. We also had a > > "messages and codes" manual. > > > > They have now all been merged into one big set of html pages - which I > > sometimes find impossible to use, for example searching for a topic, > now > > produces thousands of hits. Searching within one "book" would give few > > hits. > > > > I've used tools like pdftk < > https://www.pdflabs.com/tools/pdftk-the-pdf-to>to > > extract sections from the IBM TCPIP books ( eg for Pagent) and extract > just > > the pages I needed. I also use these subset pdf files. For example > > searching for "port" in the TCPIP books finds thousands of hits. > > Searching for port in the extracted sections gave fewer, more relevant > > hits. > > > > I created my own pdf from chapters in various pdf manuals. For example > the > > TCPIP netstat command. the z/OS operator commands I used (but could not > > remember the syntax), some MQ commands, and a few DB2 commands. I > printed > > it and had it spiral bound. I think it was about 50 pages. You can then > > put the little tabs on the pages -- green = TCPIP yellow = MQ to help > you > > locate the pages. > > > > I also have a "useful.txt" file on Linux, and use it to store > information ( > > in one line per item) for commands I use, but the fingers do not > remember. > > I just used *grep pdf useful.txt* and it just gave *pdftk > > ~/apdf/TCP/IP_reference24.pdf cat 930-946 output tls.pdf* > > > > With a little work you can avoid printing reams of output. > > > > Colin > > > > On Wed, 22 Oct 2025 at 06:49, Brian Westerman < > > [email protected]> wrote: > > > >> 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 > >> > > > > ---------------------------------------------------------------------- > For IBM-MAIN subscribe / signoff / archive access instructions, > send email to [email protected] with the message: INFO IBM-MAIN > ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to [email protected] with the message: INFO IBM-MAIN
