> I don't abbreviate in documentation or discussion. Hmmm. I think referring to the console command P resonates with people more than STOP. I wonder if people do not recognize XMIT better than TRANSMIT. The goal in documentation should be clarity, not pedagogics.
I once had an all-out war (I won! I was the president!) with a tech writer who insisted that the documentation should spell out Multiple Virtual Systems on the first reference to MVS (in technical documentation for a hardcore mainframe product). My position was that it made us look like idiots. Charles -----Original Message----- From: IBM Mainframe Discussion List [mailto:[email protected]] On Behalf Of Paul Gilmartin Sent: Sunday, October 3, 2021 6:23 AM To: [email protected] Subject: Re: PL/I vs. JCL On Sat, 2 Oct 2021 20:56:43 -0700, Charles Mills wrote: >I have no problem with the DD/member ambiguity: > >1. If it's a personal tool and you are happy with the ambiguity, then you >are happy. >2. If it's a "product" then you just document which takes priority. > o z/VM CP and CMS with their very flat syntax (no delimiters) allow keywords to be elided when their values do not overload other keyword names. And some operands are required for admin users and optional or prohibited for general users. And VM nerds delight in abbreviating keywords and command names to single characters, baffling novices. Ugh! o UNIX command options can be ambiguous with (non-portable?) filenames beginning with "-". The resolution is to qualify with current working directory: "./-whatever". I don't abbreviate in documentation or discussion. I write ALLOCATE, not ALLOC; TRANSMIT, not XMIT; etc. (Oops! I wrote "admin" above.) >I wrote a (successful!) product that in one very peripheral feature took an >operand that could represent a member name in a default PDS, a dataset name, >or a zFS file name. I differentiated among the three based on length and the >presence or absence of periods and/or slashes. No one ever complained that >they had a dataset or a zFS file named SHORTNAM and could not reference it. >I think the convenience and simplicity of being able to say simply >FILENAME(whatever) outweighed the perils of the ambiguity. Product design >involves tradeoffs. -- gil ---------------------------------------------------------------------- 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
