A good tech writer is a joy forever; one who will polish prose describing the delivered product in such a way that it still describes the delivered product. The other type is more common, and is reminicent of root canal.
-- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 ________________________________________ From: IBM Mainframe Discussion List <IBM-MAIN@LISTSERV.UA.EDU> on behalf of Greg Price <greg.pr...@optusnet.com.au> Sent: Monday, September 7, 2020 11:04 AM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Constant Identifiers On 2020-09-05 3:01 AM, Paul Gilmartin wrote: > If the number 3.1416 is used in more than one place in the program, > or if it requires specific data or precision attributes, you must declare > it as a named constant. In the olden days - years before the iPhone 6 was a thing - there were people called Technical Writers. Now-a-days we have Information Developers, referred to as ID. A few years back there seemed to be a religious phase where IBM ID went on a crusade to remove weasel words from documentation. (I'm no longer at IBM, so I don't know if this "phase" persists or not.) This seemed to take the form of global changes whenever a new version of the manual was being prepared, where every instance of a word on the "weasel list" was replaced by its more definite counterpart. For example, something like: "If the PDS directory is corrupt then the library scan may abend." became "If the PDS directory is corrupt then the library scan will abend." The latter sentence implies that if the library scan did not abend then the PDS directory cannot be corrupt in any way, which was not the original information that the author was trying to convey. You can -> You must It may -> It will It should - It will That last one is probably the sort of thing they were really trying to fix, I expect, as in: "If there is an I/O error, the scan should skip the bad block." "If there is an I/O error, the scan will skip the bad block." As it was, whole sections of text I wrote for our product took on meanings I hadn't intended, and sometimes the "edited" text became outright lies. Anyway, in case you haven't guessed yet, that's what I think happened in the quoted item from the PL/I LRM. Cheers, Greg ---------------------------------------------------------------------- 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
