Framework Documentation with Patterns: Characteristics and Opportunities from Five Series of Controlled Experiments (original) (raw)
Related papers
2011
Good design and implementation are necessary but not sufficient prerequisites for successfully reusing object-oriented frameworks. Although not always recognized, good documentation is crucial for effective framework reuse, and often hard, costly, and tiresome, coming with many issues, especially when we are not aware of the key problems and respective ways of addressing them. Based on existing literature, case studies and lessons learned, the authors have been mining proven solutions to recurrent problems of documenting object-oriented frameworks, and writing them in pattern form, as patterns are a very effective way of communicating expertise and best practices. This paper presents a small set of patterns addressing problems related to the framework documentation itself, here seen as an autonomous and tangible product independent of the process used to create it. The patterns aim at helping non-experts on cost-effectively documenting object-oriented frameworks. In concrete, these patterns provide guidance on choosing the kinds of documents to produce, how to relate them, and which contents to include. Although the focus is more on the documents themselves, rather than on the process and tools to produce them, some guidelines are also presented in the paper to help on applying the patterns to a specific framework.
Patterns for effectively documenting frameworks
Lecture Notes in Computer Science (including subseries Lecture Notes in Artificial Intelligence and Lecture Notes in Bioinformatics), 2011
Good design and implementation are necessary but not sufficient prerequisites for successfully reusing object-oriented frameworks. Although not always recognized, good documentation is crucial for effective framework reuse, and often hard, costly, and tiresome, coming with many issues, especially when we are not aware of the key problems and respective ways of addressing them. Based on existing literature, case studies and lessons learned, the authors have been mining proven solutions to recurrent problems of documenting object-oriented frameworks, and writing them in pattern form, as patterns are a very effective way of communicating expertise and best practices. This paper presents a small set of patterns addressing problems related to the framework documentation itself, here seen as an autonomous and tangible product independent of the process used to create it. The patterns aim at helping non-experts on cost-effectively documenting object-oriented frameworks. In concrete, these patterns provide guidance on choosing the kinds of documents to produce, how to relate them, and which contents to include. Although the focus is more on the documents themselves, rather than on the process and tools to produce them, some guidelines are also presented in the paper to help on applying the patterns to a specific framework.
Patterns for documenting frameworks-process
Recife, Brazil, May, 2007
Good design and implementation are necessary but not sufficient pre-requisites for the successful reuse of object-oriented frameworks. Although not always recognized, good documentation is crucial for effective framework reuse and comes with many issues. Defining and writing ...
Evaluating documenting techniques on frameworks of object-oriented code
2011
This research work empirically investigated different documentation philosophies for effective transfer of knowledge in teaching new framework users. Six controlled experiments were set up to compare the various documentation philosophies, namely patterns-style, minimalist and extended javadoc (Jdoc) documentation. These knowledge transfer strategies and tests were evaluated within two different frameworks. Subjects' exercises were used to gather data, the results from which were used to formulate guidelines for effective framework documentation. The discoveries in this paper were two fold. First, the statistical analyses such as univariate analyses of variance show that the effect and impact of the various documentation strategies are different. Second, different effectiveness of the patterns-style when applied to different frameworks was discovered. The formulated guidelines will be used to serve as an important roadmap for instructors who wish to integrate framework documentation into their teaching and learning environments. Different documentation philosophies are better for different goals. For a simple task, use minimalist documentation. For a much more complex problem, the empirical results suggest using patterns-style documentation.
Documenting frameworks using patterns
Sigplan Notices, 1992
The documentation for a framework must meet several requirements. These requirements can all be met by structuring the documentation as a set of patterns, sometimes called a "pattern language". Patterns can describe the purpose of a framework, can let application programmers use a framework without having to understand in detail how it works, and can teach many of the design details embodied in the framework. This paper shows how to use patterns to document a framework, and includes a set of patterns for HotDraw as an example.
Leveraging Framework Documentation Solutions for Intermediate Users in Knowledge Acquisition
Frameworks are increasingly emp loyed as a useful way to enable object-oriented reuse. Ho wever, understanding frameworks is not easy due to their size and co mplexity. Prev ious work concentrated on different ways to document frameworks, but it was unclear which ones actually were better. Th is paper presents a novel way of investigating the different philosophies for framework documentation. The philosophies include minimalist, patterns-style and extended javadoc (Jdoc) documentation. Using a survey of 90 intermediate users engaged in Co mmand and Adaptor design patterns coding work, this exp loratory study discovered that minimalist documentation has positive impacts in encouraging knowledge acquisition, significantly in terms of the framewo rk functional workings. This concludes that documentation solutions with the min imalist principle can lead intermed iate users to faster growth in learning two o f the design patterns.