See discussions, stats, and author profiles for this publication at: https://www.researchgate.net/publication/228217510 The Information Systems Documentation - Another Problem for Project Management Article · November 2006 CITATIONS READS 4 11,335 2 authors, including: Gabriela Mesnita Universitatea Alexandru Ioan Cuza 23 PUBLICATIONS 65 CITATIONS SEE PROFILE Some of the authors of this publication are also working on these related projects: ie2018 - The 17th International Conference on Informatics in Economy, May 17 – 20, 2018, IaČ™i, Romania View project Agile project management View project All content following this page was uploaded by Gabriela Mesnita on 04 June 2014. The user has requested enhancement of the downloaded file. Managing Information in the Digital Economy: Issues & Solutions 332 The Information Systems Documentation – Another Problem for Project Management Prof. Dumitru Oprea, PhD, "Alexandru Ioan Cuza" University, Iasi, Romania, E-mail doprea@uaic.ro Assoc. Prof. Gabriela Mesnita, PhD, "Alexandru Ioan Cuza" University, Iasi, Romania, E-mail gabim@uaic.ro Abstract generated at the end of each stage, as a partial project result. We see important trends for information systems that influence their development, including that of the specific documentation. As a result, the ways to approach systems from the perspective of IT project management, responsibilities and resource allocation and also from the perspective of the importance of the documentation change to ensure the success of a development project. The plot thickens when the developing team is scattered geographically, the implementation characteristics of the new system differ from one company location to others, and the users have more and more requirements and claims regarding the documentation quality. The documentation of information system is a component of communication, control and monitoring of the development, operation and maintenance project. At the same time, the documentation should be regarded as one of the results of the stages of the system life cycle. This is why, the system documentation is important from the viewpoint of the project management and of its development and operation. Unfortunately, one can find that most often in practice the documentation is either incomplete or totally missing. This paper attempts after a revision of the documentation typology, to present the causes and the effects generating the lack or the incompleteness of the system documentation and the identification of the persons that are responsible for its developing and upgrading. 1. Introduction We are not hearing rarely from the information system specialists statements like: "we cannot change the program, because we don't know how it was conceived", "we cannot modify the database scheme, because the way in which it was designed is not clear", "we cannot include another module in the application, because there is nothing linked to the application structure" and so forth. Such circumstances occur when the system that is being operated requires changes and improvements, difficult to perform these, making in most cases the decision to initiate a new development project, knowing that it is much easier to do something from the very start than to change something existing. Yet, what is the reason for which a new systems starts to be developed in the presented context? One of the answers is the documentation, meaning that it does not exist or is incomplete or not upgraded and therefore it cannot be used in the process of system maintenance. Moreover, the system documentation can be transformed in a factor of project failure, having regard to the passage from one stage to another, within the development cycle, takes place on the basis of the information collected within the specifications The documentation is often regarded only as an additional volume of information that is available to the organization and to the project team that, as some think, slows down the performance of a project. This opinion can be accepted if we consider the speed and the necessity of system changing or replacement [10], [9], [1]. Yet such a position may have an expensive effect in the long term, as revealed in the following paragraphs. Let us not forget, for the work's sake, the problem we started with. Trying to complete the chapter on documentation of the book Information System Design, we found no structured approach or, as Fitzgerald says [3], formalised approach, but there are not many materials with a clear point of view and no common one. Hence the idea of project in project to which we might refer later. 2. Typology of information system documentation The documentation of a project is an instrument for recording various decisions and actions involved by the life cycle of a project and the means by which decisions and actions are documented and justified. The creation of documents may help the project team in conducting activities and reaching the fixed objectives, representing the support for obtaining the approvals necessary for the stage performance, resource allocation, and the performance of the control from the part of the project manager or of the sponsors. Hence, any project including the information system developing project is based on a documentation made up of a series of documents designed during the project life cycle. Any project stage normally should end with a set of documents used as starting point in making decisions for continuing the project, for establishing how the activities specific to the next stages are to be performed and what measures are necessary for observing the project schedule and budget if they are exceeded or for changing the initial project specifications. In other words, the documentation of each stage enables on the one hand to monitor and control the project and on the other hand, to conduct the stages provided initially. Electronic copy available at: http://ssrn.com/abstract=946785 Managing Information in the Digital Economy: Issues & Solutions 333 The project documentation may be structured depending on the project stage to which it refers, that is [13], [9], [8], [20], [16]: For the conception stage of the specific project plan, there is a project plan, an official document approved and used for the management and the control of the project performance, being a collection of documents that may be changed in time as more pieces of information are obtained. The project plan is a quite elaborate structure, being the essential element in conducting it. Besides the project plan, after it is conceived, other supporting details are obtained, that comprising the documentation obtained during project conception (for instance, assumptions that have not been provided earlier), technical specifications and projects if any, the documentation for the standards used in appreciating the project quality. Within the project performance stage, several reports will be generated emphasizing the way in which activities were performed, how the quality standards required were followed, how the schedule and budget were keep on limit, the requests to make changes to the projects, the licenses needed for performing works etc. To these are added the forms and the documents used to emphasize the resource allocation and use, the achieved results, the contract follow-up etc. For the change control stage, the specific elements are the upgraded project plan and the forecasts on the future of the project as documents. Upon project completion, there occur some contractual adjustments, including decisions for some problems that remained unsolved and the project completion report that contains a synthesis of how the project was conducted, of the changed coming on the way, of the achieved results. The contents of the project documentation differ also depending on the categories of the involved persons, such as [14], [22], [1], [7]: • • • the approval committee or the project sponsor should have the project proposal, with the justification of its necessity, the feasibility study, the project plan, the reports on project evolution; for the organization that will implement the project results, the analysis cost/benefit, the project draft and plan, the documentation of how to use the results are necessary; for the project team, there are necessary the following pieces of documentation: the project plan, the documents of evidence of the resources used, the reports on project evolution, the documentation related to the achievement of the project results, the contracts with the suppliers or the consulting companies, the approved requests for changing certain aspects of the basic plan and so forth. The system documentation is a product/result of the performance of a project, the purpose of which is to communicate the project and system information to all the interested parties, from sponsors, users, specialists and up to the management of the organization where the new system will be implemented. Although there are similitude between the project documentation and the information system documentation, it is important to make a distinction between them, even if the latter is integral part of the former. As for the information system documentation as well one can resort to the two classification criteria, namely the stages performed for it's developing and the categories of persons that request or that has to receive information on the development stage. According to the stages of the system life cycle, we can identify: 1. the documentation of the system microanalysis, which contains a set of documents obtained during the initiation of the project or already existing, the most important ones being: the strategic plan of system development at the level of the organization, the request of system development, the pre-feasibility and the feasibility reports, the detailed plan of the initiated project, the calendar planning of the project, the managerial and communication plan and procedures, the plan of resources, the project preliminary budget; 2. the specifications or the analysis documentation, that formalize the results achieved at this stage. Its purpose is to communicate the results to the interested ones, also serving as a milestone for the following stages, first for the design stage. Therefore, a very precise description, even a mathematical one, is preferred in most cases, but we have to take into account the fact that the specification should be easily understandable by the system users as well, which means that usage to a natural language and to a series of images is more easily grasped and understood; 3. the design documentation, by which the way the system will be developed in order to meet the requirements, introduced in the analysis specifications. In the set of documents of this stage, the description or the model of all system inputs and outputs, of the processing processes, of the user-interfaces should be found. It is recommended to include any time possible examples of screens/forms for collecting data, control procedures or procedures related to the user's interaction with the system. Furthermore, the elements regarding the organization manner of the program and application modules, of the control and security procedures of applications and data, the database structure, the procedures of Electronic copy available at: http://ssrn.com/abstract=946785 Managing Information in the Digital Economy: Issues & Solutions 334 ADVERTISING and MARKETING Documentation OTHER INTERNAL AND EXTERNAL STAKEHOLDERS Documentation IMPLEMENTATION Documentation DESIGN Documentation Information System Documentation OPERATION and MAINTENANCE Documentation OTHER POTENTIAL CLIENTS Documentation USERS Documentation DEVELOPMENT TEAMS Documentation BENEFICIARY Documentation ANALYSIS Documentation MICROANALYSIS Documentation A project should solve problems, not create them. Therefore, against this background, the problem that should be solved is that of communication quality at any moment of the system development cycle. To be brief, our overview of the documentation of an information system is rendered in figure 1. SPONSOR Documentation The answers to questions and the parallelism with the stages of the system development lead us to an identical approach per life-cycle stages. From the perspective of the participants to the system development project, we identify two great categories of specifications [14], [15], [17]: 1. the user documentation contains the documents that laid at the basis of the determination of the system requirements and for the approval of various prototypes or design specifications, and the user manual drafted for each functional component, having the role of presenting the way of system operation; 2. the technical documentation contains the presentation manual addressed to the management showing the overall picture of the system, accompanied by a brief description of each functional component and the operation manual described previously. Information System Documentation Furthermore, we have to take into account that the documentation of a system depends quite largely on the methodology used, if used, in system developing. Amongst other things, resorting to a set of methodology or other - the more the system developers, the more the systems methodologies does not solve the problem of documentation. The problem is the approach of the analysis and design of system as a project, and this puts an emphasis on the communication issue. Certain questions appear: Who communicates with whom? By what means? If we look at a CHAOS report [19], out of the 10 factors of success or failure, many are tightly connected to communication, which in our understanding means the system documentation. Actually, this would be another project, like the JIT (Just-In-Time) systems, this time it is not about the factory in the factory but about the project in the project. This new project, of the documentation itself, has its own decompositions depending on the solved problems, something like the Matrioshka of the end of the 19th century, when the doll contained a smaller doll, this one another even smaller doll and so on. The problem is solved by the identification of its solution, which means a good documentation (a new project) for what should be done (the project itself), how, by whom, when, with which resources and most important for whom and what it should be done for each beneficiary of the new products, that is documentation itself. Technical and/or Financial Documentation distributed processing etc are presented. Many of the component parts of the design documentation are necessary to the specialists that will participate in the performance of the following stage, having a noticeable technical character, yet they are meant also for users, because they can show many of the system facilities and the way in which one can interact with it; 4. the documentation of implementation, which comprises the elements specific to the implementation planning, the comments on program code generation, the types of tests and the test results, the procedures of system conversion etc; 5. the instruction manual, describes the main elements regarding system operation, the way of interacting with it, the particularities of every application module, the help system, the way of resolving any error, the access levels of various categories of users etc; 6. the operation manual presents the system operation and maintenance conditions that lay at the basis of any intervention to eliminate any bug found during system testing, to add new items or to improve the existing ones. Fig. 1 Different documentation categories depending on stakeholders and stages of life cycle development Managing Information in the Digital Economy: Issues & Solutions 335 With regard to the previous figure, we have to mention that not all documentations specific to the stages of the system development cycle address to all categories of interested persons. These is, for instance, the case of the potential clients or other in-house or out-house stakeholders for which only the advertising and marketing documentation presents interest, any other kind being useless. Based on our brief analysis of the typology made, we can see that the documentation volume of a system is considerable. Hence, there results that it is necessary to observe certain standards and drafting procedures and to make a rigorous control on upgrades during operation and maintenance, having regard to the fact that the new systems are subject to a great pressure of changing and adaptation to the dynamics of the technological and economic environment. 3. The role of the information systems documentation The drawing up of the system documentation is considered as one of the project activities that involve a high costs level and are great timeconsumers, which often results, at the end of the projects, into a form of this documentation that is no longer extremely useful [18], [6], [15]. Although specialists have different opinions on the role of the system documentation, we shall list here possible uses of this component of the structure of a system [21], [11], [6]: • a means of clarification of certain aspects during system development, namely finding answers for various problems that may occur during the project; • a sort of contract between the project team members and the system beneficiaries or between the team and the management of the organization or of the department where the system is to be implemented. Specifications, and especially analysis specifications, become, most of the times, contract clauses, following talks with the users, on the continuation of the system development, which makes it impossible for the user to alter certain requirements stipulated in the approved specifications; • a means of communication between the project team members, that is the essential component for the performance of the various activities specific for each stage of the development cycle. The team members often initiate certain activities only after having clarified all the problems of the previous stages and after having documented the solutions that they had identified; • a support when making decisions on the choice of the design alternatives, as, due to the details provided by the analysis documentation, the • • team together with the project manager and the organization management may decide on the best solution for the further system development; the analysis and design documentation is a starting point for system implementation, verification and validation; the final system documentation is the keyelement for insuring its proper operation and maintenance; the documentation shall be updated whenever the initial operation components are altered. All the above-mentioned aspects refer strictly to the system development cycle, but one should consider that system documentation also provides an efficient management of the development project. Based on its contents, the project may be supervised and monitored, there can be required changes of the basic project plan, the project sponsor may be provided with different reports and there can be coordinated the meetings with the system users or beneficiaries. From the viewpoint of the project management, this documentation is useful when analyzing the fulfillment by the team members of their assignments, when identifying possible problems that may arise and prevent the team from reaching their goals, the approval of the financial resources needed for the following stages. Despite these possible uses of the documentation of an information system development project, one can notice great deficiencies, both at the level of the systems developed in-house, and of those developed by specialized companies. The following paragraph will be focusing on the causes and effects of the absence or incompleteness of this documentation. 4. Causes and effects of the information system documentation deficiencies The importance of documentation in system development projects has not been yet fully understood. Many specialists emphasize on the importance of documentation, without pointing out, however, its qualitative features. In fact, most of the times, documentations are incomplete and rarely updated, which diminishes its quality and reliability. Furthermore, starting from the works of Fitzgerald [3], [4], [5] in which the problem of system development methodologies is approached, containing references to other materials of the other authors, we find that in system development, the documentation plays a very important role. Translating the problems tackled by Fitzgerald, we may come to the assumption that documentation is not approached in a formalised way that would provide it a status of critical factor in the success of developing a system, assumption that we want to validate in a future study. Managing Information in the Digital Economy: Issues & Solutions 336 Nevertheless, resuming our initial opinions, let us try to identify the reasons and people responsible for the failure of most of the system documentation to provide satisfactory information both to the users and to the team project or to the sponsor. First, here are some of the most frequent causes: • failure to observe the initial timetable, but the need to observe the date of completion, by reducing the time allocated to certain activities considered less important, among which documentation drawing up and updating; • failure to observe the project budget, knowing that the documentation drawing up and updating involve additional costs, which means that a first step taken to observe the budget is to give up the efforts and costs required by this activity; • lack of interest of the people directly using the documentation, since reading it takes time, and verbal communication is easier and less timeconsuming. However, according to the Latin saying, "verba volant, scripta manent"; • drawing up of a single documentation for all those involved in the system development project, using a language that is not always understood by all those interested in reading the documentation; • absence of clear formalisms concerning the contents of the documentation; • there have not been established the dates when the documentation is supposed to be issued and updated; • absence of policies, standards and procedures to be followed during system development, and implicitly for the documentation drawing up and updating; • there is nobody, neither a person, nor a group of persons, with assignments for the drawing up and updating of the project documentation. At a first glance, an absent or an incomplete documentation does not seem to affect to much the performance of the project or the system operation. This is however a false statement, as its effects are numerous, namely: • during the talks with the users, due to the absence of a written document including the requirements, rules, restrictions and other items needed for the determination of the functional and nonfunctional system components, debated on and approved by the users, the latter may change their initial requirements whenever they want. This may result into a longer requirements assessment time, hence a delay of the whole project; • a longer period of time needed for the analysis of the existing system, based on interviews, questionnaires, observation, due to the lack of documentation, which may be used to identify that items that should be preserved from the legacy system; • • • • • as is the case with the previous effect, the design stage may also fail to use or alter existing programs or applications, due to the lack of documentation; difficulties in defining and evaluation the design alternatives, due to a superficial documentation, especially as regards the requirements of the new system, of the components of the old system that should be incorporated; problems in establishing the system testing and conversion plans, due to the absence of the analysis and design documentation, which means they are unable to establish the precise types of test required, the data test, the items that should undergo conversion, as well as the methods of conversion; difficulties related to the system maintenance, due to the lack of guidance required for the change or replacement of certain components, especially when the project team members have left the organization as well; increase of the costs with the redesign of certain components of the system and even the costs with the development project of the new systems, as it is impossible to reuse some system components. Who is responsible for this kind of problems? As usual, the guilt is thrown back and forth, that is the project managers say that the technical team of the project is in charge with the drawing up of the documentation, and the latter consider that the project manager is the one who should insure the coordination and control of the documentation drawing up. The truth lies somewhere in the middle, since both the project manager and the technical team should be directly involved in drawing up and updating the documentation. A brief survey of literature [12], [6], [2], [9] and our experience led to the following conclusions: • the analysis specifications should be created and updated by the project manager and the analysis team; • the design and programming team is in charge with the design documentation; • the implementation specifications are the responsibility of a mixed team, made of analysts, designers, programmers, supervised by the project manager; • the instructions manual should be mainly the responsibility of the analysts (as they are the closest to the users), but also the designers and programmers; • the operation manual should be the result of the efforts of the designers, programmers. One may notice that it is impossible for one person or one group of person to take full responsibility, since the whole team should be involved in the drawing up of the documentation. However, why are there problems related to the documentation, when these responsibilities are supposed to be clearly defined. Managing Information in the Digital Economy: Issues & Solutions 337 As mentioned above, the project manager is interested rather in completing the project on time and observing the allocated budget, than in satisfying the requirements of the system beneficiary, failing to give the proper importance to the system documentation and, as it is often the case, failing to even include these activities in the project plan. Moreover, this is made worse by the lack of a well defined policy, with standards and rules to observe at the organization level (that is the system beneficiary or supplier), which should compel the project manager to plan, control and monitor the drawing up and updating of the system documentation, like any other activity of the development cycle. On the other hand, the specialists team think that it is rather time consuming to participate in writing the documentation, as they consider that the team communicate anyway the results and problems that occurred during the project development, forgetting however that the contents of the documentation are useful not only during the carrying out of the project, but also for the operation and maintenance of the developed system. There is also the issue of the contents, form and language used to create the documentation, considering that there are enough differences as concerns the knowledge of the future users. Most of the times, the documentation is not structured according to the needs of those who will use it and who are unhappy that they do not understand too much of a documentation written in an abstract language, containing many formalisms and charts, while the specialists are unhappy with this very informal language, which leaves room for interpretation, the lack of formalization and abstractions of the documentation. One solution would be to divide the documentation in two distinct components, one addressing to the users and the other to the specialists, but this solution is hard to accept as well, since it involves increased documentation drawing up efforts. 5. Conclusion The development of the information system documentation is a complex issue, both from the viewpoint of the components that it should include and of the time when it should be drawn up, but also from the viewpoint of the responsibility of the people in charge with achieving this result. A system may have the fate of the famous cathedral Sagrada Familia for which, as Gaudi's project documentation is incomplete, other designers' attempts to complete it face the discontent or the rejection of its "users". One could spend a rather long time debating on the system documentation, and such a problem will probably never be fully solved, as there are several factors to be considered, among which, the most important is the human factor, since it is the one that has the greatest influence. One is free to approach the issue of the quality of the documentation, of the automatic means used for its drawing up and updating, of its role in assessing the quality of the developed systems, but one finally reaches the same conclusion: it is up to the project manager, the development team and the beneficiary to established how detailed, precise and well structured the documentation will be at the end of the project. The limit of our research consist in the theoretical literature study and own experiences concerning documentation issues and it is not based on different models or tools to test and to demonstrate part of our hypothesis or conclusions. Also, we do not approach the quality factors of documentation, the versioning system, and the automation tools to generate the set of system and project documents. The paper is a work in process so these limits represent ones of the goals of our next researches. Also, based on the analysis in this paper, a future research will be aimed at identifying the approach and the importance given to the system documentation, if actually serve a rational role or it is just a means of defense for development teams. Therefore, we shall use surveybased research as an analysis tool which will be applied to the Romanian software companies. 6. References [1] Ambler, S.W., Agile Documentation: Strategies for Agile Software Development, Retrieved April 12, 2006, from:// www.agilemodeling.com/essays/agileDocumentation .htm. [2] Andres, H.., Zmud, R.W., "A Contingency Approach to Software Project Coordination", in Journal of Management Information Systems, Vol. 18, No. 3, 2002, p. 43. [3] Fitzgerald, B., "Formalized Systems Development Methodologies: A Critical Perspective", in Information Systems Journal, 6 (1), 1996, pp. 3-23. [4] Fitzgerald, B., "The Use of Systems Development Methodologies in Practice: A Field Study", in Information Systems Journal, 7 (3), 1997, pp. 201212. [5] Fitzgerald, B., "An Empirical Investigation into the Adoption of Systems Development Methodologies", in Information & Management, 34, 1998, pp. 317-328. [6] Forward, A., Software Documentation – Building and Maintaining Artefacts of Communication, University of Ottawa, Ontario, Canada, 2002, pp. 1, 873, 10-15, 63-75. Managing Information in the Digital Economy: Issues & Solutions 338 [7] Hopkins, J.S., Jernow, J.M., "Documenting the Software Development Process", in ACM, 089791-414-7/90/1000-0125. [20] Stimely, G.L., "A Stepwise Approach to Developing Software Documentation", in ACM 089791-414-7/90/1000-0121, 1990, pp. 122-123. [8] IEEE, Standard for Software Project Management Plans, The Institute of Electrical and Electronics Engineers, Inc., New York, IEEE Std 1058-1998, pp. 2-3, 7-11. [21] Van Vliet, V., Software Engineering. Principles and Practice, Second Edition, John Wiley & Sons, LTD, Chichester, 2002, pp. 484-485. [9] Kallio, P., Niemela, E., Documented Quality of COTS and OCM Components, 2001, Retrieved October 10, 2005, from://www.sei.cmu.edu/pacc/CBSE4_papers/Kalli o-CBSE4-2.pdf. [10] Kobayashi, A., Katayama, S., Simultaneously Developing Large Quantities of Documentation: Lessons Learned from Groupmax, 2000, Retrieved October 10, 2005, from://www.stc.org/confproceed/2000/PDFs/00082 .pdf. [11] McLeod Jr., R., Jordan, E., Systems Development. A Project Management Approach, John Wiley & Sons, Inc., New York, 2002, pp. 186-187. [12] Oprea, D., Mesnita, G., Dumitriu, F., Information System Analysis, Publishing House of "Alexandru Ioan Cuza" University, Iasi, Romania, 2005, pp. 194-197. [13] Oprea, D., Project Management. Theory and Study Cases, Sedcom Libris, Iasi, Romania, 2001, pp. 105-109. [14] Oprea, D., Business Information Systems Analysis and Design, Polirom, Iasi, Romania, 1999, pp. 485-486. [15] Pressman, R.S., Software Engineering. A Practitioner’s Approach. European Adaptation, Fifth Edition, McGraw-Hill Publishing Company, London, 2000, p. 255. [16] Project Management Institute, A Guide to the Project Management Body of Knowledge (PMBOK Guide), Third Edition, Global Standard, 2004, pp. 43-47, 11-16. [17] Tilbury, J., Software specification, Tessella Support Services PLC, 1999, pp. 3-4. [18] Schiesser, R., IT Systems Management. Designing, Implementing, and Managing WorldClass Infrastructures, Prentice Hall PTR, Upper Saddle River, 2002, p. 360. [19] Standish Group, CHAOS Report (1994), 1999, Retreived May 25, 2002, from://www.standishgroup.com. View publication stats [22] Project Management – Guidelines, Retrieved July 6, 2005, from://www.projectmanagement.tas.gov.au.