bellon@haydn.kulesat.uucp (05/24/89)
We are looking for a documentation system that can help the researchers
in our image processing group to use and maintain the central software
package. This package is a set of routines (written in Pascal, running on
a VAX under VMS). Two classes of routines are used : a large class standing
for frequently used basic operations, and a class of routines that incorporate
rather specific algorithms that researchers have written and adapted to be
useful to other people in the group too. A problem with this central software
is the documentation :
- we don't have a nice system that allows 'novice' users to check whether
there are some routines available that perhaps do what they need. The
documentation for all routines has been incorporated in the VMS help
facility, but a user must have some idea on the name of the routine
before he can get help on it. This makes a lot of fine software not being
used as intensively as it could, and leads to unnecessary duplication of
programming efforts.
- It is difficult to maintain the documentation if routines are added or
changed. People are enthousiastic enough about writing software, but not
about providing documentation files. Besides, as we are not a software
house that delivers a 'finished' product : our in-house software package
keeps changing.
We suppose that software tools are available that can assist in the retrieval
and, especially, in the maintenance of documentation. In what follows, we
will give some features of the 'ideal' system we have in mind. We would
appreciate if anyone could give some information about the existence of such
a system (either commercial or public domain). The system has not to conform
exactly to the ideas we have in mind : any suggestion is welcome. If you do
not know about a documentation tool, but you can give some hints, please do so.
Some features we can think of (although others could probably do also) :
- Once the documentation is in the 'database', it should be possible to
get help using a keyword or using (a part of) the name of a specific
routine. If a keyword is given, some general information on that topic
should appear and a list of routines dealing with that topic. If the
name of a routine is used, detailed information on the routine should be
given, and references to further routines or to keywords.
- The information on a particular routine can consist of different sections
that are either very standardized (the routine header, a list of the
parameters and their purpose), or rather informal (the desciption of the
algorithm...).
- We think the most critical part of the system is the facility for
adding and changing information. The package is likely to change often.
Furthermore, we depend on the goodwill of the person who provides the
routine to also provide the information. The system should do as much
as possible automatically.
- It would be great if the facility for inserting/changing information would
be accessible from the editor when changing the source code of the routine
itself. The possibility of mixing the programming work with the creation
of documentation would faciliate and probably motivate the programmer to
provide consistent documentation.
- If the parameter list of a procedure is changed, the system should detect
this and ask the programmer for documentation (or at last keep saying the
documentation is not up to date).
- We do not consider speed to be critical. Versatility and beeing professional
is considered more important than speed.
Erwin Bellon (Software Manager)
Katholieke Universiteit Leuven
Dept. Elect. Engineering
ESAT / MI2
Kard. Mercierlaan 94
3030 HEVERLEE
Belgium
Tel. 32 - 16 - 220931 (ext. 1041)
Email : ...!kulcs!kulesat!bellon (UUCP)
bellon%kulesat.uucp@blekul60 (BITNET)
psi%02062166012::bellon (PSI MAIL)