On Sun, Oct 3, 2021 at 6:59 AM Charles Mills <[email protected]> wrote:
> > 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 > -- Skip Robinson 323-715-0595 ---------------------------------------------------------------------- For IBM-MAIN subscribe / signoff / archive access instructions, send email to [email protected] with the message: INFO IBM-MAIN
