Pattern: Knowledge Keeping

You want to keep what you have learned while understanding the framework. You want to be able to use that knowledge in the future so that you don’t have to do it all again. Also you want it to be fit for other framework users.

Problem

Learning how to use a framework means finding, browsing, using and generating understanding knowledge. Reusing the knowledge in future learning tasks is as useful as reusing design and code. Developers go to great lengths to create and maintain rich mental models of code that are rarely permanently recorded. Preserving this knowledge for later use is, therefore, of utter importance.

How to adequately preserve the acquired learning knowledge?

Forces

Existing Documentation. Adopting existing documentation artefacts as templates to harbour new knowledge depends on its availability, easiness of use and quality of its contents.

Intrinsic knowledge. Much relevant information is kept in the minds of experts that have used the framework. This knowledge decays with time and never becomes useful to others but the expert himself. Sharing this knowledge is important, but might be expensive to experts as it causes interruption and can be time-consuming.

Tools. Documentation generation tools, using recovery and extraction techniques, might be used to generate several specific kinds of views and formats over the information about the framework.

Motivation. Producing documentation can be tiresome and boring. The long-term cost-benefit is often overlooked, thus affecting the motivation to spent time and resources producing documentation.

Solution

Use documentation methodologies and tools to produce documentation artefacts and store them in an open, shared, collaborative environment where the information can be accessed and evolved through time.

Choose the documentation artefacts that most adequately can register the knowledge you’ve acquired, namely FRAMEWORK OVERVIEW, GRADED EXAMPLES, CUSTOMIZATION POINTS, DESIGN INTERNALS and COOKBOOK AND RECIPES.

Consequences

Shared knowledge base. The learning knowledge is shared through the community of learners, from experts to novices, being all able to use and improve it according to their needs.

Collaborative effort. By opening the knowledge to the community, its quality improves from the constant revising by a heterogeneous group of learners, grasping all the benefits this can bring.

Rationale

Good quality documentation is crucial for the effective reuse of object-oriented frameworks. Without a clear, complete and precise documentation describing how to use the framework, how it is designed, and how it works, the framework will be particularly hard to understand and nearly impossible to use by software engineers not initially involved in its design.

Documenting a framework is not trivial. Producing framework documentation needs to address several issues ranging from contents consistency to contents organization. Using framework documentation also poses a problem where issues like understandability, searchability, and effectiveness need to be adequately addressed [Agu03].

Adopting known documentation artefacts [AD05b][AD06][AD07] specific to our learning task to store our understanding knowledge helps to lessen the burden of recording our findings. If that knowledge is then shared with a community of other fellow users, that burden can be even less because the responsibility of keeping the information up-to-date is also shared by the other contributors.

The “community” factor also contributes to the refining and quality increase of the documentation as factors like diversity, independence, decentralization and aggregation [Sur05] will mitigate quality issues like accommodating different audiences, having different views over the information or even the lack of standards.

Table of Contents