Re: Does this make no sense or is it just me?
What you see is all you get (WYSIAYG), the truth behind WYSIWYG.. From: IBM Mainframe Discussion List on behalf of Paul Gilmartin <000433f07816-dmarc-requ...@listserv.ua.edu> Sent: Monday, February 7, 2022 8:58 AM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Does this make no sense or is it just me? On Mon, 7 Feb 2022 09:12:19 -0400, Eric D Rossman wrote: >"Seymour J Metz" wrote: >> >> The ISPF Edit Ref. does give REXX examples, but there are issues >> with some of them. >> Often ineptly, needlessly prefixing each command with ADDRESS ISREDIT when a single setting of the command environment would suffice. It may have been mindlessly translated from CLIST. >> The lack of synchronization would have been easy to fix had IBM >> continued using BookManager markup instead of WYSIAYG word processors. >> "A"‽ I see. The demise of reusable code. >I'm not going to air any dirty laundry but I definitely got the impression >that many of the pubs writers would agree with you regarding BookManager. > It's a pity that Bookie couldn't have been given backends to generate PDF and HTML to support viewers prevalent on multiple platforms. But I understand one driver was sheer size: Bookie couldn't accommodate the growth of PoOps or HLASM, e.g. -- gil -- 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
Re: Does this make no sense or is it just me?
On Mon, 7 Feb 2022 09:12:19 -0400, Eric D Rossman wrote: >"Seymour J Metz" wrote: >> >> The ISPF Edit Ref. does give REXX examples, but there are issues >> with some of them. >> Often ineptly, needlessly prefixing each command with ADDRESS ISREDIT when a single setting of the command environment would suffice. It may have been mindlessly translated from CLIST. >> The lack of synchronization would have been easy to fix had IBM >> continued using BookManager markup instead of WYSIAYG word processors. >> "A"‽ I see. The demise of reusable code. >I'm not going to air any dirty laundry but I definitely got the impression >that many of the pubs writers would agree with you regarding BookManager. > It's a pity that Bookie couldn't have been given backends to generate PDF and HTML to support viewers prevalent on multiple platforms. But I understand one driver was sheer size: Bookie couldn't accommodate the growth of PoOps or HLASM, e.g. -- gil -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
Re: Does this make no sense or is it just me?
"Seymour J Metz" wrote: > Redundancy is only part of the cost. Historically, when they > replicate information on syntax for other components, they get it wrong. > > The ISPF Edit Ref. does give REXX examples, but there are issues > with some of them. > > The lack of synchronization would have been easy to fix had IBM > continued using BookManager markup instead of WYSIAYG word processors. I'm not going to air any dirty laundry but I definitely got the impression that many of the pubs writers would agree with you regarding BookManager. Given how long we were a web deliverable (instead of tied to a z/OS release), ICSF tried very hard to NOT embed any explanations, examples, etc for other products. Instead, we tried to link/point to other pubs where the real experts could describe their own product. The only things related to other products in our pubs were actual samples we shipped (like dataset allocation samples, ICSF started proc, etc) Eric Rossman, CISSP® ICSF Cryptographic Security Development z/OS Enabling Technologies -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
Re: Does this make no sense or is it just me?
> There was a tendency to put every topic in every manual. Even when the tech writer did not understand the topic. They often incorrectly inferred rules from examples, or gave examples with, e.g., JCL errors. -- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of Charles Mills [charl...@mcn.org] Sent: Sunday, February 6, 2022 3:59 PM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Does this make no sense or is it just me? There was a tendency to put every topic in every manual. I have an OS/VS COBOL P/G in front of me (1981) and it includes a lot of JCL tutorial: there is an entire three-page section titled "Examples of DD Statements Used To Create Data Sets." Charles -Original Message- From: IBM Mainframe Discussion List [mailto:IBM-MAIN@LISTSERV.UA.EDU] On Behalf Of Seymour J Metz Sent: Sunday, February 6, 2022 7:20 AM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Does this make no sense or is it just me? RCF sent. There is a similar problem when an author describes invoking something from CLIST, JCL or REXX, describes syntax and gets it wrong. That is an issue that has contined from OS/360 to z/OS. -- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of Tony Harminc [t...@harminc.net] Sent: Friday, February 4, 2022 7:20 PM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Does this make no sense or is it just me? On Fri, 4 Feb 2022 at 18:07, Charles Mills wrote: > > Does the following make sense to anyone? From the JCL Reference, at least > several recent versions including V2R5, Chapter 6. Job control statements on > the output listing. It seems boggled to me on several levels. I don't think > it is true, and I think the references to specific programs are superfluous > (or alternatively, incomplete). Am I off base? > > EXEC overriding parameters: A procedure EXEC statement appears in the job > log listing exactly as it > appears in the procedure. Overridden parameters must be shown by the program > being executed: > > . For the EXEC statement that executes the assembler program, the Diagnostic > Cross Reference and > Assembler Summary produced by the assembler program shows the overriding > parameters. > > . For the EXEC statement that executes the linkage editor, the linkage > editor listing shows the overriding > parameters. I think this is probably a classic result of the interaction among product developers, tech writers, and support/change team people. Certainly it's not correct, but more than that, I think it just reflects this uneasy mix of people with the same high level goal but different understanding. I speculate: Someone probably complained to IBM that the EXEC statement in the JCL listing doesn't directly show the result of the various substitutions that are possible. (Of course there are the SUBSTITUTION JCL messages, but they're virtulaly unreadable.) Someone in JCL (what I think of as the IEF team) said "well of course we don't show that - it's up to the program being invoked to show its own arguments after everything is resolved. For example, the assembler shows that stuff right at the top." The tech writers didn't really understand that, but went to the ASM people and asked how to explain the example of showing the overriding parameters. Someone there told them it's under the rubric "Diagnostic Cross Reference and Assembler Summary" So they put that in the book as an example, and then someone else complained that there is no example for the linkage editor. So they put that in. Then someone complained about something else, and they thought, OK, enough, and stopped putting in examples. What's obviously missing is someone with the big picture who would understand that the level of explanation and examples is all wrong, and that a more general explanation of how *any* program you invoke *may* provide a listing of its arguments, but that what the JCL resolves to is found in those SUBSTITUTION JCL messages. Just maybe a reminder about MSGLEVEL would be appropriate. I see this all the time for much smaller products that I work on; the tech writers are forever trying to clean up and organize while responding to complaints and requests for clarification from customers and Support. They think of themselves as the core of the document production process, who refer to SMEs (Subject Matter Experts) for the technical nitty-gritty. But no amount of technical detail is enough by itself when the overall view is missing. Who should provide that? It depends on the sizee and nature of the organization. Ideally one needs a single senior developer who is very competent in written English as well as both the immediate subject matter and the larger environment both technical and documentary. And who isn't spending 120% of his/her time on writing code. So it goes.
Re: Does this make no sense or is it just me?
Redundancy is only part of the cost. Historically, when they replicate information on syntax for other components, they get it wrong. The ISPF Edit Ref. does give REXX examples, but there are issues with some of them. The lack of synchronization would have been easy to fix had IBM continued using BookManager markup instead of WYSIAYG word processors. -- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of Paul Gilmartin [000433f07816-dmarc-requ...@listserv.ua.edu] Sent: Sunday, February 6, 2022 7:32 PM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Does this make no sense or is it just me? On Sun, 6 Feb 2022 12:59:03 -0800, Charles Mills wrote: >There was a tendency to put every topic in every manual. I have an OS/VS >COBOL P/G in front of me (1981) and it includes a lot of JCL tutorial: there >is an entire three-page section titled "Examples of DD Statements Used To >Create Data Sets." > Yes. The TSO Rexx Ref. tries to teach too much TSO syntax. The ISPF Edit Ref. tries to teach too much CLIST syntax. (Why not Rexx, if anything. But it's getting better lately.) The cost of this is the burden of redundant updates if the command environment changes. And the risk of failure to synchronize updates. The JCL Ref. has separate chapters for "DD *" and "DD DATA". Parts have been copied from one to the other without needed changes. I've suggested in vain that they be consolidated with side notes for the very few differences. -- gil -- 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
Re: Does this make no sense or is it just me?
On Sun, 6 Feb 2022 12:59:03 -0800, Charles Mills wrote: >There was a tendency to put every topic in every manual. I have an OS/VS >COBOL P/G in front of me (1981) and it includes a lot of JCL tutorial: there >is an entire three-page section titled "Examples of DD Statements Used To >Create Data Sets." > Yes. The TSO Rexx Ref. tries to teach too much TSO syntax. The ISPF Edit Ref. tries to teach too much CLIST syntax. (Why not Rexx, if anything. But it's getting better lately.) The cost of this is the burden of redundant updates if the command environment changes. And the risk of failure to synchronize updates. The JCL Ref. has separate chapters for "DD *" and "DD DATA". Parts have been copied from one to the other without needed changes. I've suggested in vain that they be consolidated with side notes for the very few differences. -- gil -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
Re: Does this make no sense or is it just me?
There was a tendency to put every topic in every manual. I have an OS/VS COBOL P/G in front of me (1981) and it includes a lot of JCL tutorial: there is an entire three-page section titled "Examples of DD Statements Used To Create Data Sets." Charles -Original Message- From: IBM Mainframe Discussion List [mailto:IBM-MAIN@LISTSERV.UA.EDU] On Behalf Of Seymour J Metz Sent: Sunday, February 6, 2022 7:20 AM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Does this make no sense or is it just me? RCF sent. There is a similar problem when an author describes invoking something from CLIST, JCL or REXX, describes syntax and gets it wrong. That is an issue that has contined from OS/360 to z/OS. -- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of Tony Harminc [t...@harminc.net] Sent: Friday, February 4, 2022 7:20 PM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Does this make no sense or is it just me? On Fri, 4 Feb 2022 at 18:07, Charles Mills wrote: > > Does the following make sense to anyone? From the JCL Reference, at least > several recent versions including V2R5, Chapter 6. Job control statements on > the output listing. It seems boggled to me on several levels. I don't think > it is true, and I think the references to specific programs are superfluous > (or alternatively, incomplete). Am I off base? > > EXEC overriding parameters: A procedure EXEC statement appears in the job > log listing exactly as it > appears in the procedure. Overridden parameters must be shown by the program > being executed: > > . For the EXEC statement that executes the assembler program, the Diagnostic > Cross Reference and > Assembler Summary produced by the assembler program shows the overriding > parameters. > > . For the EXEC statement that executes the linkage editor, the linkage > editor listing shows the overriding > parameters. I think this is probably a classic result of the interaction among product developers, tech writers, and support/change team people. Certainly it's not correct, but more than that, I think it just reflects this uneasy mix of people with the same high level goal but different understanding. I speculate: Someone probably complained to IBM that the EXEC statement in the JCL listing doesn't directly show the result of the various substitutions that are possible. (Of course there are the SUBSTITUTION JCL messages, but they're virtulaly unreadable.) Someone in JCL (what I think of as the IEF team) said "well of course we don't show that - it's up to the program being invoked to show its own arguments after everything is resolved. For example, the assembler shows that stuff right at the top." The tech writers didn't really understand that, but went to the ASM people and asked how to explain the example of showing the overriding parameters. Someone there told them it's under the rubric "Diagnostic Cross Reference and Assembler Summary" So they put that in the book as an example, and then someone else complained that there is no example for the linkage editor. So they put that in. Then someone complained about something else, and they thought, OK, enough, and stopped putting in examples. What's obviously missing is someone with the big picture who would understand that the level of explanation and examples is all wrong, and that a more general explanation of how *any* program you invoke *may* provide a listing of its arguments, but that what the JCL resolves to is found in those SUBSTITUTION JCL messages. Just maybe a reminder about MSGLEVEL would be appropriate. I see this all the time for much smaller products that I work on; the tech writers are forever trying to clean up and organize while responding to complaints and requests for clarification from customers and Support. They think of themselves as the core of the document production process, who refer to SMEs (Subject Matter Experts) for the technical nitty-gritty. But no amount of technical detail is enough by itself when the overall view is missing. Who should provide that? It depends on the sizee and nature of the organization. Ideally one needs a single senior developer who is very competent in written English as well as both the immediate subject matter and the larger environment both technical and documentary. And who isn't spending 120% of his/her time on writing code. So it goes. Tony H. -- 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
Re: Does this make no sense or is it just me?
RCF sent. There is a similar problem when an author describes invoking something from CLIST, JCL or REXX, describes syntax and gets it wrong. That is an issue that has contined from OS/360 to z/OS. -- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of Tony Harminc [t...@harminc.net] Sent: Friday, February 4, 2022 7:20 PM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Does this make no sense or is it just me? On Fri, 4 Feb 2022 at 18:07, Charles Mills wrote: > > Does the following make sense to anyone? From the JCL Reference, at least > several recent versions including V2R5, Chapter 6. Job control statements on > the output listing. It seems boggled to me on several levels. I don't think > it is true, and I think the references to specific programs are superfluous > (or alternatively, incomplete). Am I off base? > > EXEC overriding parameters: A procedure EXEC statement appears in the job > log listing exactly as it > appears in the procedure. Overridden parameters must be shown by the program > being executed: > > . For the EXEC statement that executes the assembler program, the Diagnostic > Cross Reference and > Assembler Summary produced by the assembler program shows the overriding > parameters. > > . For the EXEC statement that executes the linkage editor, the linkage > editor listing shows the overriding > parameters. I think this is probably a classic result of the interaction among product developers, tech writers, and support/change team people. Certainly it's not correct, but more than that, I think it just reflects this uneasy mix of people with the same high level goal but different understanding. I speculate: Someone probably complained to IBM that the EXEC statement in the JCL listing doesn't directly show the result of the various substitutions that are possible. (Of course there are the SUBSTITUTION JCL messages, but they're virtulaly unreadable.) Someone in JCL (what I think of as the IEF team) said "well of course we don't show that - it's up to the program being invoked to show its own arguments after everything is resolved. For example, the assembler shows that stuff right at the top." The tech writers didn't really understand that, but went to the ASM people and asked how to explain the example of showing the overriding parameters. Someone there told them it's under the rubric "Diagnostic Cross Reference and Assembler Summary" So they put that in the book as an example, and then someone else complained that there is no example for the linkage editor. So they put that in. Then someone complained about something else, and they thought, OK, enough, and stopped putting in examples. What's obviously missing is someone with the big picture who would understand that the level of explanation and examples is all wrong, and that a more general explanation of how *any* program you invoke *may* provide a listing of its arguments, but that what the JCL resolves to is found in those SUBSTITUTION JCL messages. Just maybe a reminder about MSGLEVEL would be appropriate. I see this all the time for much smaller products that I work on; the tech writers are forever trying to clean up and organize while responding to complaints and requests for clarification from customers and Support. They think of themselves as the core of the document production process, who refer to SMEs (Subject Matter Experts) for the technical nitty-gritty. But no amount of technical detail is enough by itself when the overall view is missing. Who should provide that? It depends on the sizee and nature of the organization. Ideally one needs a single senior developer who is very competent in written English as well as both the immediate subject matter and the larger environment both technical and documentary. And who isn't spending 120% of his/her time on writing code. So it goes. Tony H. -- 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
Re: Does this make no sense or is it just me?
Tony, thanks for the thorough response. I wanted a reality check. I will submit an RCF. Charles -Original Message- From: IBM Mainframe Discussion List [mailto:IBM-MAIN@LISTSERV.UA.EDU] On Behalf Of Tony Harminc Sent: Friday, February 4, 2022 4:21 PM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Does this make no sense or is it just me? On Fri, 4 Feb 2022 at 18:07, Charles Mills wrote: > > Does the following make sense to anyone? From the JCL Reference, at least > several recent versions including V2R5, Chapter 6. Job control statements on > the output listing. It seems boggled to me on several levels. I don't think > it is true, and I think the references to specific programs are superfluous > (or alternatively, incomplete). Am I off base? > > EXEC overriding parameters: A procedure EXEC statement appears in the job > log listing exactly as it > appears in the procedure. Overridden parameters must be shown by the program > being executed: > > . For the EXEC statement that executes the assembler program, the Diagnostic > Cross Reference and > Assembler Summary produced by the assembler program shows the overriding > parameters. > > . For the EXEC statement that executes the linkage editor, the linkage > editor listing shows the overriding > parameters. I think this is probably a classic result of the interaction among product developers, tech writers, and support/change team people. Certainly it's not correct, but more than that, I think it just reflects this uneasy mix of people with the same high level goal but different understanding. I speculate: Someone probably complained to IBM that the EXEC statement in the JCL listing doesn't directly show the result of the various substitutions that are possible. (Of course there are the SUBSTITUTION JCL messages, but they're virtulaly unreadable.) Someone in JCL (what I think of as the IEF team) said "well of course we don't show that - it's up to the program being invoked to show its own arguments after everything is resolved. For example, the assembler shows that stuff right at the top." The tech writers didn't really understand that, but went to the ASM people and asked how to explain the example of showing the overriding parameters. Someone there told them it's under the rubric "Diagnostic Cross Reference and Assembler Summary" So they put that in the book as an example, and then someone else complained that there is no example for the linkage editor. So they put that in. Then someone complained about something else, and they thought, OK, enough, and stopped putting in examples. What's obviously missing is someone with the big picture who would understand that the level of explanation and examples is all wrong, and that a more general explanation of how *any* program you invoke *may* provide a listing of its arguments, but that what the JCL resolves to is found in those SUBSTITUTION JCL messages. Just maybe a reminder about MSGLEVEL would be appropriate. I see this all the time for much smaller products that I work on; the tech writers are forever trying to clean up and organize while responding to complaints and requests for clarification from customers and Support. They think of themselves as the core of the document production process, who refer to SMEs (Subject Matter Experts) for the technical nitty-gritty. But no amount of technical detail is enough by itself when the overall view is missing. Who should provide that? It depends on the sizee and nature of the organization. Ideally one needs a single senior developer who is very competent in written English as well as both the immediate subject matter and the larger environment both technical and documentary. And who isn't spending 120% of his/her time on writing code. So it goes. Tony H. -- 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
Re: Does this make no sense or is it just me?
On Fri, 4 Feb 2022 at 18:07, Charles Mills wrote: > > Does the following make sense to anyone? From the JCL Reference, at least > several recent versions including V2R5, Chapter 6. Job control statements on > the output listing. It seems boggled to me on several levels. I don't think > it is true, and I think the references to specific programs are superfluous > (or alternatively, incomplete). Am I off base? > > EXEC overriding parameters: A procedure EXEC statement appears in the job > log listing exactly as it > appears in the procedure. Overridden parameters must be shown by the program > being executed: > > . For the EXEC statement that executes the assembler program, the Diagnostic > Cross Reference and > Assembler Summary produced by the assembler program shows the overriding > parameters. > > . For the EXEC statement that executes the linkage editor, the linkage > editor listing shows the overriding > parameters. I think this is probably a classic result of the interaction among product developers, tech writers, and support/change team people. Certainly it's not correct, but more than that, I think it just reflects this uneasy mix of people with the same high level goal but different understanding. I speculate: Someone probably complained to IBM that the EXEC statement in the JCL listing doesn't directly show the result of the various substitutions that are possible. (Of course there are the SUBSTITUTION JCL messages, but they're virtulaly unreadable.) Someone in JCL (what I think of as the IEF team) said "well of course we don't show that - it's up to the program being invoked to show its own arguments after everything is resolved. For example, the assembler shows that stuff right at the top." The tech writers didn't really understand that, but went to the ASM people and asked how to explain the example of showing the overriding parameters. Someone there told them it's under the rubric "Diagnostic Cross Reference and Assembler Summary" So they put that in the book as an example, and then someone else complained that there is no example for the linkage editor. So they put that in. Then someone complained about something else, and they thought, OK, enough, and stopped putting in examples. What's obviously missing is someone with the big picture who would understand that the level of explanation and examples is all wrong, and that a more general explanation of how *any* program you invoke *may* provide a listing of its arguments, but that what the JCL resolves to is found in those SUBSTITUTION JCL messages. Just maybe a reminder about MSGLEVEL would be appropriate. I see this all the time for much smaller products that I work on; the tech writers are forever trying to clean up and organize while responding to complaints and requests for clarification from customers and Support. They think of themselves as the core of the document production process, who refer to SMEs (Subject Matter Experts) for the technical nitty-gritty. But no amount of technical detail is enough by itself when the overall view is missing. Who should provide that? It depends on the sizee and nature of the organization. Ideally one needs a single senior developer who is very competent in written English as well as both the immediate subject matter and the larger environment both technical and documentary. And who isn't spending 120% of his/her time on writing code. So it goes. Tony H. -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
Does this make no sense or is it just me?
Does the following make sense to anyone? From the JCL Reference, at least several recent versions including V2R5, Chapter 6. Job control statements on the output listing. It seems boggled to me on several levels. I don't think it is true, and I think the references to specific programs are superfluous (or alternatively, incomplete). Am I off base? EXEC overriding parameters: A procedure EXEC statement appears in the job log listing exactly as it appears in the procedure. Overridden parameters must be shown by the program being executed: . For the EXEC statement that executes the assembler program, the Diagnostic Cross Reference and Assembler Summary produced by the assembler program shows the overriding parameters. . For the EXEC statement that executes the linkage editor, the linkage editor listing shows the overriding parameters. Charles -- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
