Almost every software developer has sometime in his life been confronted with
the problem of documenting his project. This, one would say banal matter,
consists of more problems than one would think. Software that does not include
quality detailed documentation is heading for downfall. In our document we will
try to illustrate some of the possibilities for quick and effective
documentation of software product.
The basic factor to think about is the target group. Common software user is
interested in different type of information than application
developer. This needs to be taken into consideration. One needs to adapt the
form and content of documentation. That is why distinguish two different types
of documentation:
User-oriented documentation
Common user is usually not interested in software architecture nor its inner
implementation. He or she does not care how things are done, what means and
programming languages were used in the process of development. What interests
him/her the most is how the program runs, how is it used and also in what
environment and under which operation system it can be started. That is why the
emphasis should be put on detailed, but mainly understandable explanation of all
functions and possibilities of the program.
It is better if someone else than the author of the program writes the
user-oriented documentation. He may consider many things to be absolutely clear
while they may not be clear at all to the common user. It is appropriate if the
user-oriented documentation includes many examples and is written in awareness
that it will be read by person who does not understand programming at all.
Developer-oriented documentation
A developer working on a project needs to have documented all the inner
technical matters of the software, such as class inheritance hierarchy, data
structure description as well as its attributes, list of source files, global
identifiers etc. The description of the correct use of corresponding
development tools used for the program creation should also be included.
The basic purpose of existence of developer-oriented documentation is the
maintenance and extensibility of the software product. It is an absolute must
to document all the nonstandard program constructions as well as a detailed
description of the process of debuging and synchronizing the program.
It is now clear that these two types of documentation are absolutely different.
It is not possible that the documentation of the first type replaces the second
or the other way around. The developer-oriented documentation should be written
along with the program creation. If the inner implementation of structure
changes, the corresponding part of documentation is changed as well. It is
reasonable to start writing the user-oriented documentation as soon as possible,
but this should not be before the program reaches its basic functionality.
Both types of documentation are written by different people and the tools for
its creation and maintenance are adapted correspondingly. Their use is
illustrated in the following chapters of this document.
| 
Prihlásiť
Registrácia
English
