the root cause of most complaints about any form of documentation today is that we have been spoiled by search engines and that we have a lot less time to do what is right over what is expedient. the method I have been trying to sell on my job is use wikis as connective tissue to hold and make effective the flesh and bones of other documentation formats. the response has been blank looks, sneers and ugly words.
The community that consists of the members of this list could just build the future by making a site which represents their cumulative knowledge. It would require managed access to fend off trolls. Example: IBM has a nice site for a glossary for terms. But because it represents knowledge gathered from across the enterprise, it appears to be less than current and has omissions. If wikimedia software (or the equivalent) were made to have a separate permission list for each namespace,, and if automatic disambiguation were implemented, the contributions of disparate groups could seamlessly (or almost so) be merged into one knowledgebase - completely w/o a donnybrook over who is right about, oh, say, USS. pup Our greatest danger in life is in permitting the urgent things to crowd out the important. - Charles E. Hummel Efforts and courage are not enough without purpose and direction. - John F. Kennedy IBM Mainframe Assembler List <[email protected]> wrote on 08/19/2011 01:14:25 PM: > From: Steve Comstock <[email protected]> > To: [email protected] > Date: 08/19/2011 01:16 PM > Subject: Re: a new POP (was HLASM Manuals ) > Sent by: IBM Mainframe Assembler List <[email protected]> > > On 8/19/2011 10:55 AM, Martin Trübner wrote: > > While I am happy with the L.R. I like to comment on Kens' > > > >>> The "assembler" manual I would like to see rewritten is the "Principles > > of Opeertations" > > > > Absolutly.... while POP (the way it is) may have its place- I have a > > hard time reading about a certain instruction (when I need to). > > > > It is IMHO more than counterproductive (I dare to say confusing) > > for the reader (but time saving for the authors of the hardware/micro-code) > > to have identical instructions with only variations in a-mode and/ > or targets in one > > paragraph- this results in very subtle changes in the wording > > for the various flavours. I would prefer (even if this would > > create a manual three times as big) every instruction in a > > separate text. > > > > For illustration look at TRxx (xx="OT/OO/TT/TO") - or (for a simpler > > sample) look at AH/AHY/AH/AGHI. > > > > It would make life easier for everyone using this book if each of > > these instructions would be explained in a different chapter. The way > > it is now is that the reader is challenged to read all the fine print. > > > > To me it means reading the instructions at least twice (if not more). > > (and all the AH is explained in different text. > > It is an inherently complex topic. It takes work to 'get it'. And > even then, subtleties are easily missed. Who on this list has not > written an Assembler program and then five years (or even six months) > later wondered how they could write this crap? :-) > > It takes practice and experience. I'm not sure the authors can do > much better without skimming over points that come back to bite > the unsuspecting programmer later. > > Of course, a class can help speed the process. :-) > > > > > > -- > > Martin > > > > Pi_cap_CPU - all you ever need around MWLC/SCRT/CMT in z/VSE > > more at http://www.picapcpu.de > > > > > -- > > Kind regards, > > -Steve Comstock > The Trainer's Friend, Inc. > > 303-393-8716 > http://www.trainersfriend.com > > * Special promotion: 15% off on all DB2 training classes > scheduled by September 1, taught by year end 2011 > > * Check out our entire DB2 curriculum at: > http://www.trainersfriend.com/DB2_and_VSAM_courses/DB2curric.htm ----------------------------------------- The information contained in this communication (including any attachments hereto) is confidential and is intended solely for the personal and confidential use of the individual or entity to whom it is addressed. If the reader of this message is not the intended recipient or an agent responsible for delivering it to the intended recipient, you are hereby notified that you have received this communication in error and that any review, dissemination, copying, or unauthorized use of this information, or the taking of any action in reliance on the contents of this information is strictly prohibited. If you have received this communication in error, please notify us immediately by e-mail, and delete the original message. Thank you
