Abstract

Abstract

Abstract

Abstract
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 good quality documentation for a framework is often hard, costly, and tiresome, especially when not aware of its key problems and the best ways to address them. This document presents patterns from a set of related patterns that describe proven solutions to recurrent problems of documenting object-oriented frameworks. The pattern language they all form together aims at helping non-experts on cost-effectively documenting object-oriented frameworks. The patterns here presented address the problems of explaining how to use a framework and illustrating what it can be good for, respectively the patterns "COOKBOOK & RECIPES" and "GRADED EXAMPLES".

Abstract
Good documentation benefits every software development project, especially large ones, but it can be hard, costly, and tiresome to produce when not supported by appropriate tools and methods. The documentation of a software system uses different artifacts, namely source code, for low-level internal documentation, and specific-purpose models and documents, for higher-level external documentation (e.g. requirements documents, use-case specifications, design notebooks, and reference manuals). All these artifacts require continual review and modification throughout the life-cycle to preserve their consistency and value. Good software documents are often heterogeneous, i.e., they combine different kinds of contents (text, code, models, images) gathered from separate software artifacts, a combination usually difficult to maintain as the system evolves over time, considering that source code, models and documents are typically produced and maintained separately in multiple sources using different environments and editors. This paper presents a wiki that helps on quickly weaving different kinds of contents into a single heterogeneous document, whilst preserving its semantic consistency. The fundamental goal of this wiki (XSDoc Wiki) is to reduce the development-documentation gap by making documentation more convenient and attractive to developers. An example taken from the JUnit framework documentation helps to illustrate the features more relevant to do such weaving. Copyright 2005 ACM.

Abstract
Good design and implementation are necessary but not sufficient pre-requisites 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. © 2011 Springer-Verlag Berlin Heidelberg.