Abstract
Adequate documentation of an object-oriented framework is the prerequisite to its success as a reusable component. The overall design of a framework and its intended method of reuse are not obvious from the source code and thus have to be addressed in the documentation. Most importantly, the documentation of a framework has to be structured in such a way that it guarantees the adequate support of three major audiences: users selecting a framework, users learning to develop typical applications based on the selected framework, and users intending to modify its architecture.
This paper presents a model for structuring the documentation of an objectoriented framework. The model integrates existing approaches such as patterns, hypertext, program-understanding tools, and formal approaches into a single structure that is geared towards supporting the three audiences. The model will be illustrated using HotDraw, a Smalltalk framework for drawing editors, as an example. We also give a preliminary evaluation of the model.
This is a preview of subscription content, log in via an institution to check access.
Preview
Unable to display preview. Download preview PDF.
References
Apple Computer. MacApp Programmer's Guide. 1986
J.D. Arthur and K.T. Stevens. Document Quality Indicators: A Framework for Assessing Document Adequacy. Technical Report, No. TR90-60, Virginia Polytechnic Institute and State University, Blacksburg, VA, USA, 1990
K. Beck and R. E. Johnson. Patterns Generate Architectures. In Proceedings of the ECOOP'94, Springer Verlag, Berlin, 1994, pages 139–149
F. Buschmann, R. Meunier, H. Rohnert, P. Sommerlad, and M. Stal. Pattern-Oriented Software Architecture: A System of Patterns. John Wiley & Sons, 1996
J.M. Brant. HotDraw. Master's Thesis, University of Illinois at Urbana-Champaign, 1995. HotDraw is available at http://st-www.cs.uiuc.edu/users/brant/HotDraw/HotDraw.html
P. Brusilovsky. Adaptive hypermedia, an attempt to analyze and generalize. In Multimedia, Hypermedia, and Virtual Reality, P. Brusilovsky, P. Kommers, and N. Streitz, Eds., vol. 1077, Springer-Verlag, Berlin, 1996, pages 288–304
K. Czarnecki, R. Hanselmann, U. W. Eisenecker, and W. Köpf. ClassExpert: A Knowledge-Based Assistant to Support Reuse by Specialization and Modification in Smalltalk. In Proceedings of the 4th International Conference on Software Reuse, M. Sitamaran, ed., IEEE Comp. Soc. Press, 1996, pages 188–193
R.H. Campbell and N. Islam. A Technique for Documenting the Framework of an Object-Oriented System. In Computing Systems, vol. 6, no. 4, Fall 1993, pages 363–389
J. Coplien and D. Schmidt, eds. Pattern Languages of Program Design. Addison-Wesley, 1995
E. Gamma, R. Helm, R. Johnson, and J. Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley, 1995
D. Gangopadhyay and S. Mitra. Understanding Frameworks by Exploration of Exemplars. In Proceedings of the International Workshop on Computer-Aided Software Engineering (CASE '95), 1995
R. Helm, I.M. Holland, and D. Gangopadhyay. Contracts: specifying behavioral compositions in object-oriented systems. In Proceedings of the OOPSLA/ECOOP'90, SIGPLAN Notices, vol. 25, no. 10, 1990, pages 169–180
R. E. Johnson. Documenting Frameworks using Patterns. In Proceedings of the OOPSLA'92, ACM SIGPLAN Notices, vol. 27, no. 10, October 1992, pages 63–76
R. E. Johnson. Documenting Frameworks. In Frameworks Digest, vol. 1, no. 13, Oct. 26, 1994, available at ftp://st.cs.uiuc.edu/pub/FWList/v1n13
K. Koskimies and H. Mössenböck. Scene: Using Scenario Diagrams and Active Text for Illustrating Object-Oriented Programs. In Proceedings of the 18th Int. Conf. on Software Engineering, IEEE Comp. Soc. Press, 1996, pages 366–375
D.E. Knuth. Literate Programming. Center for the Study of Language and Information, Stanford University, 1992
D.B. Lange and Y. Nakamura. Interactive Visualization of Design Patterns Can Help in Framework Understanding. In Proceedings of the OOPSLA'95, ACM SIGPLAN Notices vol. 30, no. 10, October 1995, pages 342–356
G.A. Miller. The Magical Number Seven Plus or Minus Two. In The Psychology of Communication: Seven Essays, G.A. Miller, New York: Basic Books, 1967
B. Minto. The Pyramid Principle. Part One: Logic in Writing. Pitman Publishing, London, 1991. First published by Minto International Inc. in 1987
H. A. Müller, Understanding Software Systems Using Reverse Engineering Technologies: Research and Practice. Tutorial Notes, 18th Int. Conf. on Software Engineering, 1996, page 2–12
Object Technology International Inc., ENVY/Developer R3.01. User Manual, 1995
Object Technology International Inc., ENVY/QA, see at: http://www.oti.com/briefs/qa/qabrief.htm.
D.L. Parnas. On the Criteria To Be Used in Decomposing Systems into Modules. In Communications of the ACM, vol. 15, no. 12, December 1972, pages 1053–1058
Parplace-Digitalk, Inc. VisualWorks Cookbook. 1995
W. Pree, G. Promberger, A. Schappert, and P. Sommerlad. Active Guidance of Framework Development. In Software—Concepts and Tools, no. 16, 1995, pages 136–145
W. Pree. Design Patterns for Object-Oriented Software Development. Addison-Wesley, 1995
K.T. Stevens, J.D. Arthur, and R. E. Nance. A Taxonomy for the Evaluation of Computer Documentation. Technical Report, No. TR88-38, Virginia Polytechnic Institute and State University, Blacksburg, VA, USA, 1988
D.C. Schmidt. The ADAPTIVE Communication Environment: An Object-Oriented Network Programming Toolkit for Developing Communication Software. Available at http://www.cs.wustl.edu/ ~schmidt/ACE.html
P. Steyaert, C Lucas, K Mens, and T. D'Hondt. Reuse Contracts: Managing the Evolution of Reusable Assets. In Proceedings of the OOPSLA'96, ACM SIGPLAN Notices, vol. 31, no. 10, October 1996, pages 268–285
eXept Software AG, Smalltalk/X, see at: http://www.informatik.unistuttgart.de/stx/stx.html
M.F. da Silva and C.M.L. Werner. Packaging Reusable Components Using Patterns and Hypermedia. In Proceedings of the 4th International Conference on Software Reuse, M. Sitamaran, ed., IEEE Comp. Soc. Press, 1996, pages 146–155
F. Tip, J.-D. Choi, J. Field, G. Ramalingam. Slicing Class Hierarchies. In Proceedings of the OOPSLA'96, ACM SIGPLAN Notices, vol. 31, no. 10, October 1996, pages 179–197
S.R. Tillay, S. Paul, and S. B. Smith. Towards a Framework for Program Understanding. In Proceedings of the 4th Workshop on Program Comprehension, A. Cimitile and H.A. Müller, eds., IEEE Comp. Soc. Press, 1996, pages 19–28
W. Tracz. DSSA (Domain-Specific Software Architecture) Pedagogical Example. In ACM SIGSOFT Software Engineering Notes, vol. 20, no. 4, July 1995
Author information
Authors and Affiliations
Editor information
Rights and permissions
Copyright information
© 1997 Springer-Verlag Berlin Heidelberg
About this paper
Cite this paper
Meusel, M., Czarnecki, K., Köpf, W. (1997). A model for structuring user documentation of object-oriented frameworks using patterns and hypertext. In: Akşit, M., Matsuoka, S. (eds) ECOOP'97 — Object-Oriented Programming. ECOOP 1997. Lecture Notes in Computer Science, vol 1241. Springer, Berlin, Heidelberg. https://doi.org/10.1007/BFb0053392
Download citation
DOI: https://doi.org/10.1007/BFb0053392
Published:
Publisher Name: Springer, Berlin, Heidelberg
Print ISBN: 978-3-540-63089-0
Online ISBN: 978-3-540-69127-3
eBook Packages: Springer Book Archive