Call for feedback, participation - software maintenance documentation research project

[Phil Cohen <pcohen -at- hci -dot- com -dot- au>]

(The relevance of this posting to TECHWR-L lies in the maintenance
documentation aspects of the research ...)

The University of Western Sydney (UWS), with assistance from HCi, is
planning a major research project to look into an underexplored area of
software engineering: just what are the drivers of software maintenance costs?

Software maintenance costs account for about two thirds of total software
costs , and yet research on what can be done to reduce these costs has
concentrated on factors such as coding style and language.  Very little work
has been done on real-world inputs that might affect costs: the maintenance
environment and toolset, and the level of maintenance documentation left
behind by the developer.

As a first step, the project has been awarded a seed grant which it intends
to use to initiate the project.  The project will be in the following stages:
With the seed grant, UWS will:
· perform a literature search
· identify a candidate set of metrics
· collect some data from real projects

The next stage will be a larger project, subject hopefully to a SPIRT grant,
which will:
· collect further data on the useful metrics identified from the seed project
· fit a heuristic which will allow the effect on costs to be predicted
· publish the results

Feedback

The purpose of this document is to generate feedback on the proposal from
people in the software industry.  The remainder of this document talks in
some detail about the methods to be used and the areas to be examined.  All
feedback should be sent to the project's director, Dr Wai K Chan at the UWS
Department of Computing and Information Systems at wk -dot- chan -at- uws -dot- edu -dot- au

Participation

Industry partners can be closely involved in stage two of the project, to:
· provide material and advisory support to the project
· provide information on actual maintenance costs
· work with the researchers to learn more about how to cut maintenance costs

To become involved, email Dr Chan, or email Phil Cohen at HCi on
pcohen -at- hci -dot- com -dot- au

Metrics

The project is based on the following model:
 <diagram can't be included on a TECHWR-L posting - but contact me if you
want the Word version of this posting>

SPICE is an international standard for measuring software process maturity.

To measure the tools and environment for a given product, the
presence/absence of the following features of the environment will be used
to develop a metric:
· Document search by project, version and operations performed
· Component search by project, version, spec and design
· Interfacing of development tools
· Task modelling of roles in development and maintenance
· Reuse support through creation of templates
· Interconnection of process templates for process optimisation
· Creation, modification and deletion of relations among documents and their
contents
· Identification of document where no link exists
· Tracking of design, code and test documentation associated with a system
function or requirement
· Tracking of requirements tested by a given formal procedure
· Identification of procedures that test a component
· Making design decisions basing on managerial requirements and language
constraint and forecasting relations among the resulting templates
· Tracking the origin of an approved change to the source development
trouble report
· Production of an anatomy of the approved change and estimating the effort
in man-month for its completion
· Performing program slicing analysis on the relevant module to determine
the location of the problem
· Performing regression test to reinsert the module back into the system.
· Provision of a comprehensive library of software metrics for monitoring
progress and resources expended

Metrics for documentation will be based on measurements of the documentation
artefacts available to the maintenance programmers.  The documentation
metrics identified as candidates are:
· word count
· coverage (what percentage of programs, etc, are actually documented)
· overview percentage (what percentage of the documents are conceptual, as
opposed to documenting particular elements or objects)
· readability measures (Fog, etc)
· age differential (how up to date is the documentation vis a vis the code
it documents)

The documentation artefacts under study will include:
· code comments (excluding those automatically generated by configuration
management systems, etc)
· maintenance documentation, including system overviews, design documents,
program specs
· data dictionaries and file layouts
· communications protocols, etc

What next?

If you have:
· suggested additions to the above list of metrics
· suggested changes in approach or focus
.. then contact Dr Chan.
If your organisation would like to be involved in a research project which
can potentially reduce the cost of two thirds of its software lifecycle ...
then Phil Cohen.

_____________________________________________________________________
Phil Cohen, Director
____________________
HCi (R)                      Better Communications Better Management.
(61-2)9283-4799 (ph)                            http://www.hci.com.au
(61-2)9283-5344 (fax)          GPO Box 4846 Sydney NSW 2001 Australia
_____________________________________________________________________