Supplementing IBM Manuals Tom Bergeron I like I B M manuals. I think they take s o m e unfair criticism from people, particularly those in Tech Writing seminars, who don't understand the problems their authors are up against (and often enough, have never written a full-size tech manual). I recently attended such a seminar at Southern Illinois University (Carbondale, IL) that gathered m a n y teachers of tech writing from several colleges and a few tech writers who have been toiling in the field without benefit of P h D credentials. The teachers all seem to be in favor of clear, concise language, simple expression, and well-organized logic. The writers are all in favor of recruiting students who understand the subject matter about which they are supposed to write. I'm convinced that most companies have had their best success by hiring technicians and teaching them to write, rather than hiring writers and teaching them the subject. Of course, there is controversy. M y experience with students who have true skill in creative writing and high grades in English or communication, has been that they tend to b e c o m e quite bored with the chores of gathering and presenting t e c h n i c a l m a t e r i a l . T h e y v e r y s o o n l e a v e - - o f t e n to b e t t e r p a y i n g j o b s in m a n a g e m e n t , w r i t i n g m a r k e t i n g m a t e r i a l , or j o u r n a l i s m . M e a n w h i l e , t h e y c o m p l a i n a lot, sometimes they cry, and usually they place a t r e m e n d o u s b u r d e n on e v e r y o n e n e a r b y to s p o o n f e e d t h e m t h e n e c e s s a r y m a t e r i a l . T h e y b l a m e e v e r y o n e for the lack of information -- the very information that t h e y w e r e h i r e d to p r o d u c e . B u t l e t ' s r e t u r n n o w to t h e IBM m a n u a l s . No o n e ( e x c e p t , o f c o u r s e , IBM) r e a l l y r e v i s e s t h e m t o a n y g r e a t e x t e n t . P e o p l e do c o p y m a t e r i a l f r o m t h e m in a f e w c a s e s - - m o s t l y t a b l e s , c h a r t s a n d s y n t a x d e s c r i p t i o n s . In m o s t c a s e s t h e IBM m a n u a l s a r e n o t r e p r e s e n t a t i v e o f the large scale computer installation's configuration. N o t o n l y d o e s t h e u s u a l s h o p floor c o n t a i n h u n d r e d s o f p i e c e s o f n o n - I B M e q u i p m e n t , b u t also t h e IBM s o f t w a r e is o f t e n m o d i f i e d b e y o n d r e c o g n i t i o n t o f i t t h e specific purposes of the company. When you read the b o o k s p u t o u t for u s e by a p p l i c a t i o n p r o g r a m m e r s {and u s u a l l y w r i t t e n by s y s t e m s p r o g r a m m e r s ) , y o u s e e a r e f l e c t i o n o f t h e c o n f i g u r a t i o n o f t h e s h o p floor a n d t h e m o d i f i e d s o f t w a r e t i e d in to t h e b a s i c IBM p r o s e . Typically the CPU, the operating system and the JES, TSO a n d IMS s y s t e m s r e m a i n p r e t t y m u c h i n t a c t . UCC makes heavy inroads into tape management, data dictionary and scheduling. Control Data and Itel tape d r i v e s a b o u n d . The d e s c r i p t i o n o f h o w all t h e s e p i e c e s f i t t o g e t h e r is a p r o p e r c r e a t i v e e x e r c i s e for a s y s t e m a r c h i t e c t or a s m a r t c o m p u t e r o p e r a t o r . W h e n IBM c o m p i l e r s a n d a s s e m b l e r s a r e u s e d , IBM p u b l i c a t i o n s g e n e r a l l y s u f f i c e . If s c h o o l s or o t h e r vendors have supplied such software, the writer has the p r o b l e m o f c o m b i n i n g all t h e d i f f e r e n t f o r m a t s a n d publication philosophies into one comprehensible package. When local packages have been developed, the i n v e n t o r s m u s t be t r a c k e d d o w n a n d i n t e r v i e w e d . If a n i n v e n t o r c a n also w r i t e , so m u c h t h e b e t t e r . If n o t , t h e tech writer produces the best documentation he can, b a s e d on w h a t e v e r i n t e r v i e w s , floor c h a r t s , p r o g r a m s t a t e m e n t s or i n t e r - o f f i c e m e m o s he c a n c o l l e c t . Now he checks the modifications and the m o d i f i c a t i o n s to t h e m o d i f i c a t i o n s , a n d r e v i s e s a n d r e w r i t e s e v e r y t h i n g . (I s h o u l d h a v e m e n t i o n e d e a r l i e r , of c o u r s e , t h a t c o p y r i g h t w a i v e r s n e e d to be p r o c u r e d . Also, m u c h i n f o r m a t i o n f r o m t h e o r i g i n a l m a n u a l s c a n be l e f t b e h i n d w h e n it c o n s i s t s of i n t e r f a c e , index, d i s c l a i m e r s , s a l e s p r o m o t i o n , or j u s t p l a i n filler.) What remains assembled, culled, together, indexed, manual that reflects computer room. a f t e r all t h e m a t e r i a l h a s b e e n formatted, modified, revised, tied t a b b e d , p r i n t e d a n d c o v e r e d is a the current situation at the central Sometimes the situation remains static, as described, for several weeks before the whole process starts over again. F r o m m y previous experience with publications in support of aircraft, ordnance, and rocket launching equipment, I can well imagine that IBM's efforts to produce more and better computers leaves I B M tech writers in a constant scramble to produce manuals. I can also see that I B M is forced to cover thousands of contingencies in its manuals which w e thankfully do not have to worry about at our level. In their o w n way, I B M has been outstanding in the tech publication field. Their manuals are as good as anyone else's, in m y opinion. The criticisms about vagueness, incomprehensibility, jargon, and lack of organization say more about the readers than the writers. There are few grammatical errors, typos, missing lines, or update quandaries associated with I B M publications. I think this is truly remarkable in an industry that changes speed and direction so often. So you see, the answer for most companies lies in a moderate path somewhere between complete revision and helpless dependence. This is the path of the computer oriented Tech Writer. - Z3 -

/lp/association-for-computing-machinery/supplementing-ibm-manuals-Mb5LRx06nd