Systems documentation

Abstract

We present as a practical case the payroll system developed for the Education Plannlng and Culture Offices of the Ministry of Public Education.I t is the old payroll problem, but payment normativlty in the Mexican government and the c h a r a c t e r i s t i c s of the education sector lnvolve greater complexity. Because the system is for employees" payment, i t is Important that any modification to the system be done as soon as possible (not more than a week) and with maximum r e l i a b i l i t y to get the expected resu]ts.With these considerations in mind, one of the principal obJectives at the beginning of the proJect was that documentation must be good enough to permit a programmer to become f a m i l i a r with the system and perform maintenance easily and accurately, even i f he or she was not a member of the t e a m that developed i t . We p r e s e n t t h e g u i d e l i n e s we have f o l l o w e d f o r t h e d e v e l o p m e n t and d o c u m e n t a t i o n of t h e p a y r o l l system f o r the E d u c a t i o n Plann.ing and C u l t u r e O f f i c e s of t h e M i n i s t r y of Public E d u c a t i o n . In our experience, maintenance of a system is the most time-consuming and f r u s t r a t i n g a c t i v i t y of our trade, so we have concentrated from the s t a r t of the design on easying t h i s task. One might Imagine the ideal s i t u a t i o n of a maintainer who thoroughly adopts and absorbs the knowledge, the state of mind and the experiences about a system of the o r i g i n a l d e v e l o p e r . T h i s is o b v i o u s l y i m p o s s i b l e , but in a sense, systems d o c u m e n t a t i o n can be t o u g h t of as a s y s t e m a t i c r e c o r d i n g of t h e s e v e r y i s s u e s , at l e a s t any t h a t the a u t h o r c o n s i d e r e d r e l e v a n t . We acknowledge t h a t our ideas about t h i s problem have been taken from o t h e r s o u r c e s , and we do not p r e t e n d to have i n v e n t e d b o i l i n g w a t e r . T h i s work r e p r es e n t s our e f f o r t s to m a t e r i a l i z e t h e s e i d e a s .We believe that documentation of a system must be good, concise and simple enough f o r a person to become f a m i l i a r with the system, evaluate the impact of any modification, and perform i t with ease.Furthermore, whatever changes are made in the system must be immediately reflected in the documentation.In order to l i v e by t h i s code of f a i t h , we have established f o r ourselves a set of rules f o r document a t i o n , d e s i g n , a n a l y s i s and programming of t h e system. We have developed a s o f t w a r e t o o l f o r the permanent u p d a t i n g of the o n -l i n e d o c u m e n t a t i o n . T h r o u g h o u t t h i s p a p e r , we r e s t i c t the meaning of the word system to the s o f t w a r e component of t h e g e n e r a l meaning of the word, w i t h the f o l l o w i n h i e r a r c h i c a l s t r u c t u r e : -System Subsystems Programs ModulesPermission to copy without fee all or.part of this...