S.B. Ho, I. Chai, and C.H. Tan (Malaysia)
Empirical Software Engineering, Software Maintenance,Documentation, Framework Techniques.
Frameworks are increasingly employed as a useful way to
enable object-oriented reuse. However, understanding
frameworks is not easy due to their size and complexity.
Previous work concentrated on different ways to
document frameworks, but it was unclear which ones
actually were better. This paper presents a novel way of
investigating the sequences of three philosophies for new
framework documentation. Step-by-step documentation is
the one traditionally used for software documentation.
This philosophy gives clear and sequential steps so that
people can follow them and learn how to do the task.
Minimalist documentation is random-access so that the
reader can proceed in a self-directed manner, and
promotes using small cards or pages that can be read in
the order the reader desires. Patterns centres upon the idea
of giving the solution to a problem in its context. It also
has the random-access idea of minimalist documentation,
but disagrees with it in that contextual information is not
minimal - it usually contains information other than what
needs to be done. This investigation discovered some
guidelines for effective framework documentation,
particularly in a Rapid Application Development (RAD)
environment. The results suggest that different
documentation sequences are better for different goals.