I find GPT, Grok, Gemini much faster to "search the doc" than I can. Most of the time it yields a reasonable set of pointers to what I want. Its not always right, but its far faster than me searching on my own or trying to parse various doc. That is a good use case for LLMs ... I wouldn't let it book flights for me, or find hotels but it gave me some pretty good starting points on how to get from Heathrow to Towcester for GSE. Just sayin.
On Wed, Oct 22, 2025 at 11:05 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
