Figure 1. Process and some
of the documents involved in the
software life cycle according to ISO 12007
Software Documentation
as an
Engineering Process
José R. Hilera, León A. González, José M. Martínez, José A. Gutiérrez
Departamento de Ciencias de la Computación
Universidad de Alcalá
28871 Alcalá de Henares (Madrid)
Fax: 34-918854790 E-mail: ccjjrhg, leon.gonzalez, ccjmms, ccjagm@cc.alcala.es
Summary
The convenience of applying an engineering
approach to the production and maintenance of the documents involved in the
software life cycle is taken into consideration. We suggest the integration of
CASDE technology (Computer Aided Software Document Engineering) in CASE (Computer Aided Software Engineering)
environments used for software development.
Key words:
Software Engineering, Document Engineering, Software Documentation.
1. Introduction
Traditionally, little attention has been paied
to the documentation generated during software development projects. This has
given rise to badly drawn up documents, difficult to understand, inadequate or
incomplete documents. This, as has been recognised by the principal experts in
the area of Software Enginereing [1], has hindered software maintenance
throughout the entire history of Computing, due to documentation design
deficiency, and has also degraded its
usefulness by not having available the correct information about all the
possibilities offered by the constructed software product. For these reasons
the accomplishment of quality technical documentation concerning the process,
and the software thus obtained, will be equally as important as the actual quality
of the aforesaid software.
Thus it is clearly necessary to improve the
aspects concerning document management in the development projects. That is to
say, those aspects relaed to document control by means of their complete life
cycle, from their intial creation to their final filing. Some very limited
proposals exist along these lines
regarding the treatment of documents in Software Engineering. These only
now begin to be considered by the organizations that wish to improve the
quality of the products developed, and above all, to compete in a market
dominated at present by the demands of the organizations for compliance with
quality assessment standards that allow
comlpete confidence to be placed in the results of the software project.
It is precisely these standards, in particular those of the ISO 9001 [`2] which
are considered fundamental to an adequate documentation in order to guarantee
the aforementioned quality.
2. The Complexity of Software
Documentation
The importance
of this is apparent as it deals with an element integrating the
different aspects of a software project. Standarization organizations such as
the ISO [3] or ANSI [4] have established the need to treat document management
as one more process of the software life cycle, as it is in charge of
documenting the results obtained in the remainder of the cycle.
To get an idea of the complexity and importance of documentation in software
projects, Figure 1 shows the processes established by the ISO in its norm 12007
and some of the documents involved. The treatment of these is carried out by
the so called “Documentation Process”
In view of the figure, the importance of
documentation in all ambits of a project is evident, but however, its is
precisely the aspect most neglected by the organizations dedicated to software
development. This gives rise to the paradox that projects whose objective to
produce document management software for a given orgainzation, institution of
library etc., are precislyl those that completly ignore the management of their
own engineering documentation generated by the project, with the subsequent
problems of maintaining the product thus obtained.
Both ISO and ANSI establish the convenience of
considering a documentation process that differs from the rest of the software
life cyle processes, and they break it down into a series of activities which
they consider necessary in order to execute the process. In actual fact, what
the recommendations of ISO and ANSI establesh, albeit implicitly, is that the
documentation process is an engineering process, during which the planning,
design, manufacture and maintenance of the required documents for the software
development is carried out.
Figure 1. Process and some
of the documents involved in the
software life cycle according to ISO 12007
3. Software documentation engineering
If by engineering we understood the “set of
methods, techniques and tools for the design contruction and utilization of
diverse products”, the production of the documenation containing the
information required for carrying out a software development project must also
be approached as if it were an engineering process, performing, in the first
instance, a rigorous analysis of the domental requirements in order to proceed
later to the definition and design of the identified documents. the next step
is the drawing up of the same and subsequent preparation for their
recuperation, and finally their exploitation in within the organization.
Software Documentation
Engineering must be
based on a document development methodology which establishes on the one hand,
the life cycle composed of the phases and stages that constitute the
documentary process, and on the other
hand, the set of techniques that should
be applied to each one of the activities of the life cycle.
In the Derpartment of Computing Sciences of the
University of Alcalá we have defined a methodology of this type based on the
recommendations of the ISO and ANSI. The life cycle established for the
documents is shown in figure 2.
The five phases of the life cycle are in turn
divided into a series of stages during which the joint tasks guaranteeing a complete processing of the
different management aspects of the documents involved in a project are carried
out. The objective of each one of these phases is the following.
Figure
2. Phases of the software
documentation life cycle
1. Documentation
Planning: the aim
of this phase is to study the documentation requirements of the software
project to be developed, drawing up a “Documentation Plan” which will
establish, among other things, the type of documents to be drawn up, the
technology to be used and the operations sequence for producing and
distributing the documents, and also for
the document language to be used during their indexing and referencing.
This plan will be the starting point for the following phase, that of design.
The sequence of activities to be carried our during the planning phase consists
of the following: 1) Identification of documentation requirements, 2)
Definition of the documents and their relations, 3) Establish the organization
of the documents, 4) Drawing up of a document Production and Distribution Plan,
5) Draw up a Construction Plan of the documentary language, and 6) A study of different alternative technologies.
2. Documentation
Design: Once
established the previous plan the
manner in which the documentation process will be carried out, we proceed to
the description, in the form of different conceptual models, of all the aspects
required for the production of each individual document, ranging from those
related to their internal structure to those referring to the characteristics
of its presentation to the end user, including other types of specifications,
for example those of the hypermedia type. The object of this phase is also to review the “Documentation Plan” now that
more detailed information on the documents to be produced is available. The
sequence of activities to be executed during the design phase consists of the
following. 1) Design the documents structure, 2) Design the dynamic behaviour
of the documents, 3) Incorporate the hypermedia aspects into the design, 4)
Design the documents presentation, and 4) Revise the production and
distribution plan of the documents.
3. Documentation
Production: The
object of this phase is to generate the different documents according to the
preliminary design. Each document will be drawn up with the information
produced during one or several activities of the software life cycleand shall
serve as the starting point for other project activities. During this phase, on
the basis of the contents registered in each document, the document language
will also be constructed, this will then be used in the next phase to index and
reference the documents. The sequence of activities to be performed during the
production phase consists of the following: 1) Prepare the production
environment, 2) Produce and revise the documents, 3) Construct the document
language and 4) Release (publish) the documents.
5. Documentation
Exploitation and Maintenance: This last phase of the methodolgy envisages the utilization of each document in order to exploit its contents
during the execution of detrmined activities of software development. For this,
the information contained in the document will be released or distributed to
the personnel requiring it. The activities related to the controlled
introduction of modifications to the documents
should be envisaged, and those related to the destruction of osbolete
documents, or the storing of documents
in an archive in order to form part of the documental partrimony of the
organization. The sequence of activities to be undertaken during this last
phase consists of the following. 1) Release and exploitation of the documents,
2) Carry out document maintenance, 3) File or eliminate documents.
Although the natural documentation process will
follow the general sequence of established phases, really the only phase which
should be totally completed in order to commence the next is, as can be
supposed ,the planning phase. Starting from there, what happens is that each
document is drawn up according to the specifications established in the plan, meeting
the sequence of phases for each document. For example it could occur that
several documents are designed simultaneously, that during the production of
one another is being designed, that until a specfic document undergoes exploitation others will not be
drawn up, etc.
Apart
from the management activities to be carried out on the documents involved in
the projects, the methodology support of Software Documentation Engineering
should also take into consideration the techniques to be used in such activities.
For example, one technique is required to model the structure and the static
organization of the documents, and other techniques are required to do
likewise regarding the dynamic aspects of document management; be it from the
point of view of the documentary work to be undertaken within an organization,
or be it the adoption of an approach orientated towards the interactions
produced among the documents during the execution of a documentary task,
or be it while modelling the “life” or
“states” through which each individual document may pass.
The fact that in a software project many of the
documents will be handled in an electronic format, with the result that
techniques should be proposed enabling
us to model the way in which the end-user will perceive the contents of the
document by means of a Graphic Interface on a computer screen. In this case, if
the documents are able to include multi-media elements, apart from the special
layout of the contents, their synchronization in time will have to be
established when they are diplayed before the user. This naturally requires an
additional technique. If, in addition, there exists the posibility of
establishing hyper-links which support cross-referencing in order to be able to
navigate in the contents of the documents, another technique should be offered
with which the cross references can
be modeled.
In order to make searching for the documents
easier, it would be convenient to complement the cross-referencing, based on
the hyper-links, with some other
indexing/referencing technique based on a language, for example a
Describers Thesaurus. This should, in addition, be designed and modelled using
another technique that could be similar to that used for modelling the
structure and organization of the documents. Finally, in order to facilitate
document localization and recovery
during their exploitation, another technique should be established in
the form of a document search language which allows its users to express their
information requirements.
The methodology we have drawn up in the
University of Alcalá include the definition of all these techniques required to
carry out the activities of the documentation process [5].
4. Conclusions
In this
article the need is made clear for the production of documents involved in
software development projects to be considered as an engineering process
(Software Documentation Engineering ).
Thus we propose a possible breakdown of the tasks of Document Engineering into
some twenty stages, grouped in five phases, which take into consideration both
the design and the construction and the use or exploitation of the documents..
The existance of different techniques that can serve as tools in order to carry
out the documentary tasks is also established as necessary.
Just as occurs in other branches of
engineering, the aplication of a documental methodology will not really be
effective unless an automated environment is available to serve as a support in
carrying out the established activities. For example, it is unthinkable to make
design models of the structure of
documents and their relations without an adequate tool prepared for this
purpose. Furthermore, even if this was done manually, its usefulness would really be very limited, since what is
required is that any document constructed verify designed models, the which
could be done automatically in the case of an available magnetic support
We call the technology which serves as a
support to a methodology of Document Engineering CASDE (Computer Aided Software Document Engineering). CASDE makes
reference to a Document Management System
similar to those currently in existance in the groupware environment for document production and exploitation in
groupwork [6], but improving the document recovery possibilities offered and
incorporating facilities to approach both the planning and design of the
aforesaid management, using the techniques required in each phase of the document process.
All CASE tools must incorporate a system of
this type in order to convert them into an integrated environment of documented
software development.
References.
1 Sommerville,
I. Software engineering, Addison
Wesley, Reading, MA 1992.
2 ISO 9001, Qulaity Systems – Model for
quality assurance in design development, production, installation and
servicing, International Standards Organization, Geneva, Switzerland, 1994.
3 ISO/IEC 12207, Software Life-cycle
Processes,ISO, Geneva; Switzerland, 1995
6 Khoshafian,
S. and Buckiewicz, M. Groupware, Workflow and Workgroup Computing,
John Wiley & Sons, New York, 1995.