Writing for adaptable documentation

The rapid development of reusable software components results in an information overload problem in the development process. Software developers must read large amounts of documentation. Adaptive documentation is one way to address this problem and support efficient reading. However, in our view, adaptive documentation requires a writing process that delivers the pedagogical strategies for adaptivity. The article takes a stance in a project on adaptive software reference documentation and discusses the requirements on writing. It also discusses writing trends and Web languages in relation to adaptivity. It is concluded that describing change in documentation is not supported on an authoring level but rather on a programming level.

[1]  Mary Campione,et al.  The Java Tutorial, Second Edition: Object-Oriented Programming for the Internet (Book/CD) , 1998 .

[2]  Jason Lewis,et al.  ActiveText: a method for creating dynamic and interactive texts , 1999, UIST '99.

[3]  John M. Carroll.  Minimalism beyond the Nurnberg funnel , 1998 .

[4]  Stephen Wolfram,et al.  The Mathematica book (4th edition) , 1999 .

[5]  Colin Potts,et al.  Design of Everyday Things , 1988 .

[6]  Lloyd Rutledge,et al.  A framework for generating adaptable hypermedia documents , 1997, MULTIMEDIA '97.

[7]  Douglas Kramer,et al.  API documentation from source code comments: a case study of Javadoc , 1999, SIGDOC '99.

[8]  Peter Brusilovsky.  Methods and Techniques of Adaptive Hypermedia , 1996 .

[9]  JoAnn T. Hackos.  Online documentation: the next generation , 1997, SIGDOC '97.

[10]  Erik Berglund,et al.  Use-Oriented Documentation in Software Development , 1999 .

[11]  Mary Campione,et al.  The Java Tutorial: Object-Oriented Programming for the Internet , 1996 .

[12]  Eliezer Kantorowitz,et al.  The adaptable user interface , 1989, CACM.

[13]  Elliot Soloway,et al.  Designing documentation to compensate for delocalized plans , 1988, CACM.

[14]  Arndt von Staa,et al.  Documentu : a flexible architecture for documentation production based on a reverse-engineering strategy , 1998 .

[15]  Peter Brusilovsky,et al.  Adaptive hypertext and hypermedia : proceedings of the 2nd workshop, Pittsburgh, Pa., June 20-24, 1998 , 1998 .

[16]  Lyn Dupre,et al.  BUGS in Writing: A Guide to Debugging Your Prose , 1995, IEEE Software.

[17]  Donald E. Knuth,et al.  Literate Programming , 1984, Comput. J..

[18]  Peter Brusilovsky,et al.  Adaptive educational hypermedia: From ideas to real systems , 1995 .

[19]  Robert Jacobson,et al.  Information Design , 2000 .