Google for "task oriented documentation", AKA "trash oriented documentation", and weep.
Yes, reference manuals should be complete and use cases should be in the users' guides. And, yes, the indexing is appalling for messages with hundreds of special cases. It should be easy to find the explanation of a specific RC and reason from, e.g., TOC, search bar, without a sequential search. -- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 ________________________________________ From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of Robert Garrett [rob...@garrettfamily.us] Sent: Tuesday, December 7, 2021 10:41 AM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Trying to use long parm= in started task I tend to agree about the tech writers "having lost their way". I wish they'd quit messing with "the tool formerly known as Knowledge Center", because every time they revamp it, they make it WORSE, not better. It did used to be simple. A reference manual ought to show every possible option/parameter/setting with a brief description of what each one does, ALL IN ONE PLACE!. Please, stop trying to "guess" at what "most" users are going to want to use, and tell me EVERYTHING! Let me decide which items are relevant to me, and stop making me have to hunt down a gazillion different disjoint locations in the doc and still not be certain that I've found every possible setting/option/parameter - thankyouverymuch. And messages doc? Give me a search index on the FULL FREAKING MESSAGE IDENTIFIER!! I don't know whose idea it was to set up the search index so that you have to in advance "know" that you have to break the message identifier itself down into sub-strings (of varying length of course) and drill down into sections of the message doc in order to find anything, but that person or persons ought to be horse-whipped. And the doc itself has become pretty horrible. How many times have you gone through the ordeal of finding the doc for a message, and when you finally do find it, all it tells you are things that you already knew (something went wrong) and for the solution you should "ask your systems programmer". Well, I AM the systems programmer, and the reason I'm looking up the silly message in the first place is because I don't know what went wrong in enough detail to know what to do about it. I mean come on. Someone had to write some code to detect a condition and issue the message, right? At least tell me what conditions are being checked that can trigger the message along with a little detail. How difficult could that possibly be? A user's guide ought to have examples of usage, picked to supplement/illuminate the information provided in the reference manual. As much of pain as it was to file paper TNL's into paper manuals, back when I had a whole wall's worth of them in binders in a floor to ceiling bookcase in my office behind my desk, I guarantee I could find anything I wanted to know in less than half the time it takes to use the "KC", and be at least twice as confident that the information I'd found was both complete and correct. Grrr... Yeah, I'm that olde -----Original Message----- From: IBM Mainframe Discussion List <IBM-MAIN@LISTSERV.UA.EDU> On Behalf Of Colin Paice Sent: Tuesday, December 7, 2021 2:54 AM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Trying to use long parm= in started task > The tech writers have lost their way. A Reference manual should specify syntax: how to code a command legally; and semantics: what that command does as coded. A Use's Gide should be task oriented: what command described in the < I've been on both sides of the fence writing and as an end user. The perfect solution would be to have a link to "usage" from the command reference and vice versa. This is hard in PDF. It would tend to say "go and look in the usage book" (See below) With the knowledge centre conceptually there are no "books", so the cross linking should be easy. The table of contents is book based. I think MQ pubs are only KC, and you cannot easily get PDF documents. I doubt if there is the resource to put all the links in, but from the usage statistics per page in the KC, they should be able to find the hot pages and put links in there. An example from the KC *Note: This document provides some examples of how you can use BPXBATCH. For more detailed information about BPXBATCH, see the description of the BPXBATCH utility and the detailed discussion on using BPXBATCH to run executable files under MVS™ environments in z/OS UNIX System Services Command Reference <https://www.ibm.com/docs/en/SSLTBW_2.2.0/com.ibm.zos.v2r2.bpxa500/toc.htm>.* This just gets me to *Table of Contents (exploded view) *in the command reference section rather than to the BPXBATCH command itself which would be easy to do. Both PDF and online KC have their good and bad points. Is there another option I have missed? Colin ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
