John, Thanks for asking...
How to improve the Assembler manuals? Well, one thing that comes
leaping to mind: WRT the Reference, I would really love it if you
would put individual build-in functions in the TOC. You do this for
Assembler statements and even system variables... Why not for
built-in functions as well. (This is something that has irked me for DECADES!)
But more than that...
Over all I think the Assembler Reference is very poorly organized. It
is hard to find things within. It is hard to understand the
implications of described functionality. The descriptions are laconic
(to say the least), and the examples are classically awful. They
cover only the fewest and the simplest, most obvious cases; they fail
to illustrate useful ranges of capabilities.
I love Assembler. I've been programming in it for nearly 50 years. I
cannot say the same for the Reference. In the entire time I've been
programming Assembler, the organization and structure of the
Reference has not changed one iota! Yes, new functionality has been
added, but I don't think that more than a handful of words of the
original text has been changed since the 1960s!
IMO, the Reference basically needs to be thrown out and rewritten
from scratch with totally fresh eyes. And it needs to be usability
tested along the way by an audience of people who do not already know
the language inside and out (or by those who can at least think that way).
I hear all the time that "Assembler is hard". It is not hard. C is
hard; Assembler is easy. It's just the manual that is hard.
I also hear grumbles that IBM manuals in general are hard. I do not
agree. Many of them have improved quite a lot in recent decades. But
not the Assembler Reference. It remains mired in its initial design,
and for whatever reason, it has escaped a competent rewrite.
Dave Cole REPLY TO: dbc...@colesoft.com
ColeSoft Marketing WEB PAGE: http://www.colesoft.com
736 Fox Hollow Road VOICE: 540-456-8536
Afton, VA 22920 FAX: 540-456-6658
At 8/18/2011 07:00 PM, John Ehrman wrote:
On June 6, John Walker noted that IBM manuals don't make it easy to find
information you need.
If you have suggestions for improving the HLASM manuals, please let me
know, either on or off this list.
Thanks for your help.
John Ehrman, ehr...@us.ibm.com
----------------------------------------------------------------------
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@bama.ua.edu with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html
