102.text

Summary of Discussion on Internal Standards (January 14, 1992)
==============================================================

There a four areas in which standards are needed:

- design documentation;

- coding;

- programmer-oriented documentation; and

- user oriented documentation.


A computer aided software design (CASD) tool will be used during
the advanced C++ school (Jan. 21-24).  It may be possible to retain
this after the course and use it to record the evolving design of AIPS++.

The possibility of using FrameMaker was discussed but many were of the
opinion that we could not impose a particular commercial desktop publishing
or word processing package on other institutions.  Texinfo and LaTeX
were also discussed; many people were not familar with Texinfo.

It was suggested (by Mark Stupar?) that AIPS++ designers write in whatever
format they are comfortable with initially and that documents be edited
into some standard format further down the line.

Many people felt that hypertext documentation was desirable but it was clear
that there needs to be some investigation of specific hypertext display and
authoring [sic] packages.

There was general agreement that a number of levels of user documentation
were required from the cookbook level to detailed explanations of each
program, including the algorithms used. [ We did not discuss the
need for manuals for AIPS++ administrators but it is clear that these
will be important. -- CF].

Mark Holdaway suggested shipping sample data and tutorial scripts with
the AIPS++ package.  Some people felt that tutorials would be ignored.

There was some discussion about who should write the user documentation.
There appeared to be agreement that user documentation should be written
by astronomers but it might be useful to hire a technical writer to
convert the initial documentation to a more polished forThere was also some uncertainty as to how much knowledge of radioastronomy
could be assumed of the user.  Some people (notably Bob Hjellming) felt
that AIPS++ documentation should explain basic interferometry but the majority
of those that expressed an opinion thought that a knowledge of basic
radioastromical techniques could be assumed and that the VLA aperture
synthesis school procedings or Thompson, Swenson and Moran were a
more appropriate source for such information.

There was consensus that the amount of redundent information in the user
documentation be minimized.  This rules out have completely self contained documentation for each "task".

Our current intent is to adopt the Plum-Hall C++ programming guidelines
when they are published, which should be any time now.  C++ style will be
enforced primarily by code review.

The final discussion was on which C++ development environment to adopt as
a project standard.  This was inconclusive: ObjectCenter is capable of
detecting problems due to memory leaks and may be easier for the naive 
programmer to use; ObjectWorks\C++ allows access to the POSIX.1 interface
and tracks the USL C++ releases more closely.

	Chris Flatters