Software documentation systems: Basic introduction to various user-oriented and developer-oriented software documentation systems. | ||
---|---|---|
Prev | Next |
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.
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.