CHAPTER 7

1. CHAPTER 7 Documentation & Maintenance

2. CONTENTS • Documentation and Coding Standard • Good Documentation • Type of Documentation • User Documentation • System Documentation • Module Documentation • Documentation Technique • Software Maintenance • New Development and Maintenance Activities Differ • Why Software Maintenance is Needed?

3. Documentation and Coding Standards • Is to enforcea rigorous set of guidelines on the development, production, testing and documentation of a product and its subsequent monitoring and maintenance • Use of comprehensive and proven standards • Avoid ambiguity, duplication, omission and contradiction • Codereadability and maintainability • A coding standard can only a feasible when followed throughout the software project

4. Common Areas For Standardization • Names • Routines • E.g. Book.BookTitle vs Book.Title CalculateInvoiceTotal() • Variables • E.g. prefix g_ for global variable, m_ for module level variable • Miscellaneous • avoid using commonly misspelled words • differences which exist between American and British English, e.g. color / colour, check / cheque • Comments • External– outside the source code, e.g. specifications, help file, and design documents • Internal– developers write within the source code at development time • Format • e.g. indentation, variable name joined with underscore or combine with mixed case http://msdn.microsoft.com/en-us/library/aa260844%28v=vs.60%29.aspx

5. Attributes of good documentation • Complete and up-to-date • Well structured, with neither too much information nor too little • Indexed • Presented in a standard form (which needs to be defined)

6. Types of documentation • User documentation • Describes the functions of the system, without reference to how they are implemented • System documentation • Includes all aspects of the system design, implementation and testing

7. User documentation • End user documentation (manuals and guides) • Written by technical specialists with input from the systems analyst and the programmer • Three types of document, one for each person who is going to use the system after its completion • Operator • User • Maintainer • User documentation can begin with the User Request which is the starting point for every software project • User request is a written and approved statement of the nature and objectives of the project and in general it will • State the problem • Assess the feasibility • Plan and schedule for implementation

8. System Documentation • Development of the systems design documentation is usually performed by the system analyst • It requires the production of sub-set specifications • Overall system specifications • Input/output specifications • Program specification • Table of contents

9. Module Documentation • Lowest level of documentation outside the source code itself • The most useful when the program needs to be maintained or improved at a later stage and it should include: • Name and function of the module • List of routines called • Input data, type, format and value range • Local variables • Description of algorithms • Internal functions / procedures with global variables listed • Data and program flowcharts • Error handling; error types and action taken • The tests performed and their results

10. Documentation - Techniques • Flowcharts • Other chart forms • Digital documentation • Multimedia programs • Screen grab tools can enhance documentation

11. Software Maintenance • Modification of a software product after delivery, to correct faults, to improve performance or other attributes, or to adapt the product to a modified environment • Typical definitions: • The bug-fixing view – maintenance is the detection and correction of errors • The need-to-adapt view – maintenance is making changes to software when its operational environment or original requirement changes • The use-support view – maintenance is the provision of support to users http://www.worldscibooks.com/etextbook/5318/5318_chap1.pdf

12. New Development and Maintenance Activities Differ • New development is, within certain constraints, done on a green field site • Maintenance must work within the parameters and contraints of an existing system "The architect and the builders must take care not to weaken the existing structure when adding a new room to an existing building. Although the cost of the new room usually will be lower than the costs of constructing an entirely new building, the costs per square foot may be much higher because of the need to remove existing walls, reroute plumbing and electrical circuits and take special care to avoid disrupting the current site." http://www.worldscibooks.com/etextbook/5318/5318_chap1.pdf

13. Why Software Maintenance is Needed? • To provide continuity of service • E.g. bug fixing, recover from failure, accommodate change in OS and hardware • To support mandatory upgrades • E.g. rules, tax laws • To support user requests for improvements • E.g. functionality, performance, customisation • To facilitate future maintenance work • E.g. code and database restructuring, updating documentation http://www.worldscibooks.com/etextbook/5318/5318_chap1.pdf