It's not enough that the writer wanted to aid human beings; the text has to actually do so.
-- 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: Friday, June 5, 2020 12:46 PM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Gratuitous EXECIO Documentation The documentation is written to aid human beings. It is not a hard-core exercise in logic. In writing doc I am often struck by a contrast to coding. In coding, if you had to do the same three-line sequence at ten places in your code the right thing would be to factor it out into a subroutine and invoke it ten times. In writing doc OTOH the reader might be better served by your repeating the same three sentences ten times rather than ten times saying "See the note at the top of page 17" (which is roughly the documentation analog of a subroutine call). It's a judgment call as to what will best help the reader. Sometimes following logic rigorously is what best serves the reader. Probably better to use a link to the JCL reference rather than doing a halfway job of explaining DD statements in a COBOL manual. But as @Tony says, EXECIO is a particular landmine for inexperienced Rexx coders. It is not wrong to make their lives easier. And no, "therefore every technically similar feature should get the same note" is not a valid corollary. Charles -----Original Message----- From: IBM Mainframe Discussion List [mailto:IBM-MAIN@LISTSERV.UA.EDU] On Behalf Of Paul Gilmartin Sent: Friday, June 5, 2020 9:15 AM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Gratuitous EXECIO Documentation On Fri, 5 Jun 2020 12:01:18 -0400, Tony Thigpen wrote: >In my experience, over 30 years of using REXX on first VM, then VSE and >now z/OS, I can't tell you how many times I have had to help people with >the EXECIO syntax as it relates to "what is a keyword" and "what is a >variable". I would put it at the top of the "common programming errors >in REXX" list. > >I have seen the following error SOOOO many times: >... "STEM" line. >Which should be: >... "STEM LINE." > >I would not consider this "gratuitous" documentation. > I'm outvoted. I shall submit one RCF for each command description that does not contain such a caution asking that one be added. (I haven't checked. Perhaps they already exist.) -- 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 ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
