Chapter 14. Packaging Patterns
Successfully implementing PBE and an associated reuse effort is about more than just identifying and building patterns. We need to eliminate friction and hurdles that prevent patterns from being consumed effectively and efficiently. In eliminating these hurdles, some of the questions that we need to answer include these:
• How do we package patterns to support consumption and reuse?
• How do we make the patterns available to others so that they are easy to find and work with?
• How do we make the patterns available in such a way that they are easy to support when new versions need to be made available?
• What if searching for a pattern fails to turn up relevant results or turns up irrelevant ones?
• Once a pattern is found, how do we make sure that people will succeed in using it?
The patterns and guidelines in this chapter will help us in ensuring that Pattern Users can easily find the right version of the right pattern and use it successfully.
Patterns
In this section we look at a couple of patterns for packaging patterns. These patterns provide guidance on how we can package documentation and how we can make patterns provisionable.
Embedded Pattern Implementation Guidance
Context
We have completed the work involved in creating a pattern implementation and want to support its reuse by making it as consumable as possible.
Problem
The likelihood of written documentation being ignored increases as the effort required to find and leverage the documentation increases. How can we eliminate hurdles related to following documented guidance and best practices?
Forces
• We need to understand how to surface guidance and documentation within selected tooling environments.
• Even if documentation is easy to find, it still needs to be well written.
• If the underlying pattern implementation is updated, we need to revisit and then redeploy the associated guidance.
• If the tooling selection changes, pattern implementation guidance will have to be migrated to the new platform.
Solution
There is a two-step approach to simplifying access to pattern implementation guidance. The first step is related to how and where the Pattern User finds and interacts with the guidance. A simple and immediate step is to embed documentation within the help system of the tooling platform. As Pattern Users attempt to apply the pattern implementation, they can quickly and easily find the documentation that supports the use of the pattern. Such an approach is successful, as it provides
• Consistency. Pattern Users are able to find guidance to support the pattern implementation in a manner that is consistent with finding guidance for any other aspect of the tooling.
• Context. Pattern Users are able to see, review, and follow the guidance within the context in which they are working. They do not have to switch focus from the tooling that hosts the pattern implementation.
The second step we can take is to investigate and then leverage mechanisms that go beyond static documentation. Being able to find guidance in a location that is consistent within the platform and to be able to review that guidance within the context of the tool is a strong first step. However, if we stop there, we’re still just giving the Pattern User a document to read. With a little effort, we can go beyond the results that can be achieved with just static documentation.
Many modern development tools, such as Eclipse, provide mechanisms that we can leverage. Some possibilities to consider include
• Automation. There are often cases where a number of steps need to be performed in sequence as we build a solution. We can use automation to guide us through the application of the pattern in a step-by-step fashion.
• Interactive examples. Use built-in web browser capabilities to include interactive guidance on succeeding with the pattern implementation. This can include videos, animations, and simulations.
• Linking to supporting materials. A pattern rarely exists in isolation, so we can provide links to related materials in the pattern implementation guidance. These can include materials related to the domain and the development process, as well as additional and related patterns.
We want to be practical and provide as much guidance as is needed. And we want to make it as easy and simple as possible for the Pattern User to consume that information and be productive in doing so.
Example
With the Eclipse platform we can include documentation within the pattern plug-in. The documentation can be integrated with the Eclipse help system so that the Pattern User can easily access it. However, we can take things a step further and provide a more interactive and automated experience. To do so with Eclipse we can use the Composite Cheat Sheet1 mechanism to lead Pattern Users through a series of steps. Composite Cheat Sheets provide the benefit of being able to automate steps, so they enable us to document and automate the workflow. This automation can consist of launching a wizard, creating a diagram, or other user actions. We can also instruct the Composite Cheat Sheet to leverage Eclipse’s built-in web browser to display images that provide further guidance on how to succeed in using the pattern implementation.
When using a Composite Cheat Sheet, we can automate steps of
• Building the input model
• Configuring the pattern
• Running the pattern
• Evaluating the output from the pattern
• Reapplying the pattern
Composite Cheat Sheets can work well with patterns, since we can guide users in how they can apply a pattern or even groups of patterns. Although our focus in this example is on using Composite Cheat Sheets in support of pattern implementations, we could also use them with pattern specifications. In addition, Composite Cheat Sheets are able to support us in consuming patterns for different purposes such as design, pattern detection, and pattern harvesting.
We can also use Composite Cheat Sheets to provide domain guidance when using more generic patterns. Thus, we can provide details and examples that relate to the domain to simplify any translation that is needed when applying the pattern within a domain.
Related Patterns and Guidelines
Document Pattern*, Make Pattern Documentation Easily Accessible*
Provisionable Pattern Implementation
Context
As the team works through one or more projects that leverage PBE, they will use a number of different pattern implementations.
Problem
As the team works with many patterns, they will need to be able to deploy those patterns and associated artifacts into their work environment. Over time and as projects change, they will need to update pattern implementations with new versions or uninstall some patterns and replace them with others. How do we support the deployment and provisioning of patterns to the Pattern User’s work environment?
Forces
• We need to understand the provisioning options for our selected tooling.
• We need to ensure that we have appropriate governance measures in place.
• If the underlying tooling changes, the provisioning approach will need to be revisited.
Solution
Change is inevitable. Project requirements will change. Patterns are living and will change. Thus, it is clear that we will be dealing with installation, licensing, versioning, and removal issues. We need to make this as simple and manageable for the Pattern User as possible. We leverage the capabilities of our tooling to create provisionable units for our patterns and their associated artifacts. Typically we determine if the target platform for our pattern implementations has the following:
• Extension management. The platform should provide a mechanism for managing extensions to the platform. This mechanism should support Pattern Users as they install, update, and uninstall pattern implementations. In addition, Pattern Users should be able to quickly ascertain which versions of which patterns are currently available.
• Packaging support. The tooling should support the packaging of our pattern implementations. Ideally, the tooling enables us to capture the metadata associated with a specific pattern implementation. Some of the metadata that we need to capture for a pattern implementation includes version, license, keywords, and support details.
• Asset repository integration. The platform should provide integration with the asset repository that the organization uses. In other words, are we able to search the asset repository from the target platform? If so, once we find a pattern implementation, is it easy to install?
• Cardinality. The platform should provide support for packaging sets of patterns together. There are cases where we want to treat a set of patterns as a single entity. The set should be installed as a single unit, updated as a single unit, and removed as a single unit.
Example
When working with the Eclipse platform, we can use its packaging mechanisms. At a minimum we can use plug-ins, the standard Eclipse extension mechanism, to contain a set of patterns. We can include some version information and other related information in this package. The Pattern User is able to see which plug-ins are installed and the version of each plug-in and can disable, uninstall, or update the plug-ins. Typically we package our plug-ins by using a mechanism called a feature. A feature provides a way for us to include licensing information, version information, and better integration with the platform than publishing as just a plug-in. It also allows us to bring a set of plug-ins together as one deployable unit.
Related Patterns and Guidelines
Make Pattern Documentation Easily Accessible*
Guidelines
These guidelines provide advice on how we document patterns, package patterns, and handle versioning.
Document Pattern
Summary
How do we ensure that the Pattern User is able to understand how to install, configure, use, and uninstall a pattern? We create and provide documentation that details the pattern, providing the Pattern User with support for installation, configuration, use, updating, and removal.
Introduction
Ideally, we find ourselves in a situation where we have created a number of patterns that are specific to the organization, and we want to make them consumable and support reuse. How do we ensure that the Pattern User is able to understand the details about installing, configuring, using, updating, and uninstalling the pattern? As we try to answer these questions, consider the following:
• We need to be able to look at working with the pattern implementation from the Pattern User point of view.
• A number of roles need to come together to support this effort, including the Pattern Author/SME, the Pattern Specification Author, and the Pattern Implementation Author.
Explanation
Document the pattern to provide the Pattern User with details on how to succeed in working with the pattern. At a minimum, details should include how to install, configure, use, update, and uninstall the pattern.
We need to consider whether the documentation is going to support a pattern implementation or a pattern specification. In the case of a pattern specification, there is a much lower requirement for additional documentation because the specification itself is a formally written document. Also, there is little to worry about in regard to installation, updates, and removal of the pattern. We can focus our efforts solely on writing the best pattern specification possible.
The need for providing supporting documentation is much higher with a pattern implementation as we are essentially deploying a piece of software. When documenting a pattern implementation, we seek to provide answers to the following questions:
• How do we install the pattern?
• How do we specify the input model? Note that it can be very helpful to provide a sample input model.
• How do we apply the pattern?
• How do elements in the input model map to elements in the output model? A table that lists each of the elements that are interpreted and how they are translated can be a useful way to answer this question.
• How can the pattern be configured?
• What is the reapply behavior?
• What are the extension points and how can the pattern be extended? There will be cases where the pattern is not quite a perfect fit, but it could serve as the basis for a new pattern that is more specific to the situation.
• Are there additional related patterns that need to be considered?
• What DSLs should be used with the pattern?
Keep in mind that there are multiple audiences for the pattern; documentation should be tailored to each of the audiences and clearly labeled to indicate which aspects of the documentation apply to which audience. Audiences to consider as we create the documentation include these:
• Pattern Users. They need to know the background of the pattern: What is it? When should it be used? They also need to know how to use the pattern: How should it be applied? How should it be configured? How can it be unapplied? Also, they need to know how to install and uninstall the pattern.
• Pattern producers. Pattern producers may attempt to leverage our pattern in future development, either through extension or creation of a compound pattern. They need to understand the pattern’s intended use, how it is implemented and designed. However, their focus is from a black-box point of view; they are not concerned about the code.
• Maintenance team. The pattern implementation, like other software deliverables, often has a longer-than-anticipated lifetime and will go through multiple releases. We need to provide support for the team that will be performing this maintenance work. Currently the maintenance team may be the team that did the original development, but as we’ve seen with other software, things change. The maintenance team will need to have a white-box view of the pattern, allowing them to understand the details behind its design and implementation. This audience needs to leverage the materials provided to the other audiences as well, so they will also have a black-box view of the pattern.
The goal is to make the pattern as consumable as possible, providing the user of the pattern with the information needed to succeed.
Related Patterns and Guidelines
Communicate Design with Patterns (Chapter 16), Document Pattern Relationships*, Embedded Pattern Implementation Guidance*, Make Pattern Documentation Easily Accessible*, Use Models in Documenting Patterns*
Document Pattern Relationships
Summary
How do we communicate which patterns should or should not be used with one another? Document the relationships between patterns, including dependencies, hierarchy, and cases where patterns are mutually exclusive.
Introduction
The team is following PBE and a set of patterns has been made available, including those acquired and those created. In following PBE, the team is aware that patterns should be used in combination. However, which patterns should be used together? Which patterns should not be used together? As we package our patterns, how do we communicate pattern relationships to the Pattern User? Considerations to keep in mind include these:
• In crafting a solution we need to recognize that multiple patterns will come together and interact.
• Ideally an asset repository is used for capturing pattern relationship information. Such an approach allows for the information to be easily updated after the pattern has been released for use, without requiring a rerelease of the pattern.
Explanation
The relationships between patterns, including dependencies, hierarchy, and cases where patterns are mutually exclusive, should be documented. As discussed earlier, when following PBE, we look to use patterns in combination, rather than in isolation. Relationships exist among patterns. In some cases a pair of patterns may be mutually exclusive; that is, the selection of one pattern may preclude the use of another pattern. In other cases there may be a hierarchy among a set of patterns such that the selection of one pattern leads to using one or more patterns that are supportive of that higher-level pattern.
A Pattern User should be able to quickly ascertain which patterns can be used together and how. This is important from both a pattern packaging point of view as well as from a pattern design point of view.
When designing a pattern, we need to be aware of its possible relationships. We want to document and detail any dependencies between the pattern and other patterns. It may be that we create a pattern catalog that defines a set of patterns and possibly some of the relationships. Or we may take things even further and define a pattern language that defines a set of patterns, their relationships, and an order in which the patterns should be used.2
As the pattern is completed, packaged, and deployed, we can leverage an asset repository to manage the pattern and to detail dependencies between the pattern and other patterns. An asset repository also provides support for Pattern Users to add feedback and detail relationships.
Figure 14.1 shows a diagram created to provide an overview of a set of SOA architectural patterns. As part of the overview the diagram indicates the relationships between the patterns within the set. The relationships that are denoted include those patterns that should be used together as well as those that are mutually exclusive. The diagram is simple and high-level and provides Pattern Users with an excellent resource to consult as they try to understand the set of patterns and how they should be used.
Figure 14.1. Simple diagram to highlight a set of SOA architectural patterns and their relationships
With the permission of International Business Machines Corporation, this material has been reproduced from IBM Redbook publication SG24-7356: Building SOA Solutions Using the Rational SDP (http://www.redbooks.ibm.com/abstracts/sg247356.html). Copyright 2007, International Business Machines Corporation. ALL RIGHTS RESERVED.
Related Patterns and Guidelines
Document Pattern*, Pattern Search (Chapter 10), Use an Asset Repository (Chapter 16)
Make Pattern Documentation Easily Accessible
Summary
How do we make a pattern easy for others to understand and work with? Make the pattern documentation easily accessible. The documentation should be easy to find and consume, supporting the Pattern User in the task at hand.
Introduction
The potential of a pattern will never be realized if Pattern Users cannot understand how to work with the pattern. How do we make it easy for Pattern Users to find and consume a pattern? Here are some considerations to keep in mind:
• We need to think about and understand the different ways in which a pattern can be consumed.
• We need to consider the lifecycle stages associated with a pattern, including locating, installing, using, updating, and uninstalling.
Explanation
Make the pattern documentation easily accessible. Finding the documentation and searching it for necessary information should be straightforward for Pattern Users.
In documenting a pattern, we need to think about the different scenarios in which someone would want guidance for the pattern and how that impacts the way we make documentation available. Some typical scenarios include
• Pattern selection. We should strive to make all documentation regarding the pattern available outside of the pattern packaging, allowing others to learn about the pattern (from either a design or a usage point of view) so that they can do so without having to first install the pattern. One scenario in which this is useful is assisting Pattern Users as they determine which pattern should be used. Metadata and summaries are useful in narrowing down the list of patterns to use, but to make a final selection, more details on how to use the pattern are needed.
• Pattern installation. Special instructions for installing a pattern implementation may be captured as documentation. When we provide a pattern to others for use, we put the pattern in a package, but installation documentation should be available outside of the package. What use is the documentation if it can be accessed only once the pattern has been installed?
• Creating compound patterns. Another scenario arises for those building new compound patterns. Again, metadata and summaries are useful for filtering the field of patterns, but more information is needed for making a final decision regarding which pattern to include in a compound.
A proper asset management strategy and associated governance policy are needed. When some documentation is outside of the pattern package, there are multiple related assets to manage. In addition, we should ensure that relationships between the assets are properly documented and detailed in the asset repository. This will enable anyone who finds the pattern in the repository to follow the relationships to the relevant and related assets.
Related Patterns and Guidelines
Communicate Design with Patterns (Chapter 16), Design Solutions with Patterns (Chapter 16), Embedded Pattern Implementation Documentation*, Refactor with Patterns (Chapter 16), Use Pattern Definitions to Understand Existing Solutions (Chapter 16), Use Patterns to Find Patterns (Chapter 16)
Package Related Patterns Together
Summary
How do we help Pattern Users to succeed in consuming multiple related patterns? Simplify how people find, consume, and work with related patterns by packaging them together.
Introduction
A number of related patterns have been created and need to be made available for reuse. How do we help Pattern Users succeed in consuming such a set of patterns? As we try to answer this question, consider these factors:
• We need to see patterns as a set of elements that work together and support one another in crafting a solution.
• We need to ensure that Pattern Users understand that although a set of patterns is packaged together, they are not forced to use all of the patterns in the set. We still need to ensure that we are using the right patterns in the right situations.
• We need to detail the relationships among the patterns packaged together.
• Capturing metrics and feedback can be more difficult for a specific, individual pattern within a set of patterns.
Explanation
Package related patterns together to simplify how people find, consume, and work with them. When we create a package, we can put multiple patterns together within it. However, we need to create the package with the right set of patterns within. We can’t haphazardly put together a random collection of patterns that don’t fit well together. Such an approach provides no value to the person who wants to use the patterns. There are multiple considerations that we need to keep in mind as we create the set, including
• Set size. Limit the size of the set by adding only those patterns that make the most sense. Consider whether we have too many packages with too few patterns in each. Too many patterns and associated packages can seem cluttered and be difficult to manage.
• Relationships. Ideally, we are building a collection that is highly cohesive. We can also look at the coupling between the patterns in the set. Does the use of one pattern require the use of another pattern?
• Simplification. We want to encapsulate a number of patterns within a compound pattern. To the Pattern User, the resulting package should appear as a single pattern rather than a collection of individual patterns.
• Expected usage. When and how will the patterns be used? Will the typical user consume all of the patterns on the same project? If not all, then what percentage would get used? Is there a clear delineation between groups of patterns and their usage profile? Would it make sense to subdivide the set of patterns into smaller packages?
• Update cycle. Because patterns are living, it’s likely that they will need to be updated over time. Are all of the patterns on the same update cycle? If not, how close are they in their update cycles? Can the ones more frequently updated wait to be released until those on longer update cycles are released? Or do we perform more updates? How mature are the patterns? How likely are the patterns to change?
• Pattern types. What types of patterns are in the set? Are they pattern specifications? Pattern implementations? Both?
• Versioning. Keep in mind that we will have to apply a version number to the artifacts. A decision has to be made about how we will version the elements that constitute this component. Do we version each element separately? Do we apply the same version number to all of the artifacts? For example, when using the Eclipse platform, we do have some flexibility in this area because each plug-in can have its own version number, and a feature used to package the set of plug-ins can be given its own version number. Take advantage of this capability; end users only ever see the version number from the feature. From a development and maintenance point of view, this extra level of granularity provides us with additional manageability. A modern and capable software configuration management and build system will help us to manage the versioning.
• Source. When we receive a package of patterns from outside the organization, what will we do if they are all packaged as individual patterns? Will we group and repackage them?
Take the time to think through and analyze what is the right decision for the situation. Would it make more sense to put a set of patterns together as a single package? Or is there more value in making them available individually? How will this decision impact those who will work with the package and the patterns within? Will the resulting asset simplify their use of the patterns or introduce unnecessary complexity into their workflow?
Related Patterns and Guidelines
Compound Pattern (Chapter 12), Pattern Packaging*, Pattern Search (Chapter 10), Update Existing Patterns (Chapter 11)
Pattern Packaging
Summary
How can we share patterns in such a way that they are easy for others to consume? Package patterns, bringing together the appropriate set of artifacts needed for successfully consuming the patterns. The user only needs to grab the package, rather than searching for all of the constituent parts.
Introduction
Patterns have been created within the organization or acquired from an outside source. Pattern Users get frustrated if it is too difficult to consume a pattern. How can we share patterns in such a way that they are easy for Pattern Users to consume? Keep in mind that
• Cultural changes can be difficult.
• Reusable assets that are difficult to find won’t be reused. Also, we need to find the right solution to our problem in the current context.
• Reusable assets that are difficult to reuse, won’t be reused.
Explanation
Package patterns so that they can easily be shared and consumed by Pattern Users. The package should bring together the appropriate set of artifacts3 needed for consuming the pattern, so the Pattern User can grab a single package, rather than find all of the individual parts. Forcing the Pattern User to fabricate the pattern from a loosely associated set of composite parts is a sure way to cause a pattern initiative to fail. As we design and build the pattern, we have great insight into the pattern and its related elements. Using this insight, we can package the pattern so that it is easy for Pattern Users to consume.
Overall the focus is on keeping things as simple as possible for the Pattern User. This is a good thought to start with, but it’s not very specific about how we can succeed with our packaging efforts. More detailed considerations for packaging a pattern include these:
• How will patterns be stored, searched, and then used?
• In the case of pattern implementations, how does the pattern install into the host environment? Can the packaging support how the pattern works with tooling?
• A pattern implementation can have an associated pattern specification. How do we make both the specification and the implementation available to Pattern Users?
• What is the relationship between source artifacts and binaries? Can our software configuration management and build system support us in building pattern packages?
• What asset repository solution will we use? How does it support the packaging of patterns? How does it impact how we will package patterns?
• How will the packaged asset be tested? Of course, we’ve already tested the pattern itself, but we also need to ensure that we have thoroughly tested the packaging of the pattern and how the pattern will be consumed. Deploying an asset that fails on installation by the end user will have negative consequences both for that asset as well as for our patterns initiative.
• The pattern should be packaged in such a way that it can be easily managed.
• How does packaging support reuse of the pattern by other Pattern Authors as they look to build compound patterns?
• What is the relationship between the pattern itself and its supporting artifacts? How do they get packaged?
• When do we release and package a pattern? When should it be rereleased/updated?
• What do we do when patterns from other sources do not have direct alignment with our own pattern packaging? Do we repackage? Allow the variation? Request new packaging from the supplier? What if the packaging does not include all of the supporting artifacts that we require from internal assets? Do we augment those packages?
The key point is that we need to plan and implement carefully how we package a pattern and make it available. We’ve already made an investment in identifying, designing, and building the pattern. All of that effort goes to waste if that’s where we stop. We’re close to the finish; however, there’s still work to be done.
Related Patterns and Guidelines
Compound Pattern (Chapter 12), Embedded Pattern Implementation Documentation*, Integrated Patterns and DSLs (Chapter 15), Make Pattern Documentation Easily Accessible*, Pattern Implementation Extensibility (Chapter 12), Use an Asset Repository (Chapter 16)
Pattern Version
Summary
How do we succeed in an environment where multiple versions of patterns exist? Use version numbers and a versioning strategy to manage and support the various instances.
Introduction
How can we tell which version is which when there are multiple versions of a pattern? Which one should we use? How do we communicate this information to Pattern Users? Considerations include these:
• Pattern producers and Pattern Users need to be aware of the pattern version in use.
• Pattern producers and Pattern Users need to understand where and how they can determine the currently supported version.
• Pattern producers and Pattern Users need to understand where and how to access version numbers for a specific pattern.
Explanation
Use version numbers and a versioning strategy to organize and support the various versions of a pattern. The key is to recognize that patterns are living, evolve over time, and are in many ways similar to other software deliverables. For this reason we need to leverage some of the best practices from other, traditional software deliverables. In this case we want to leverage a sound approach to how we version and communicate versions to the consumers and maintainers of patterns.
We’ll end up having versions of our patterns in both a software configuration management system and an asset repository. The important thing to keep in mind is that these two repositories serve different purposes and have separate lifecycles that happen to intersect at points in time. The software configuration management solution is used to provide team and versioning support for the pattern as it is being created. This applies whether we are working with specifications or implementations, and also to the associated and supporting artifacts that are related to the pattern. The list of artifacts includes documentation, samples, installation instructions, and other elements. The asset repository is used to manage and make available the assets that are to be reused by the Pattern Users. We put our final, packaged version of the asset in the asset repository. An asset repository is responsible for supporting and managing the consumption of completed patterns.
The version number should be clearly displayed in relevant places such as the packaging, the documentation (documentation that discusses installation as well as the documentation that covers usage), as well as the code and templates. A modern software configuration management and build system should be able to provide assistance in maintaining this information.
Related Patterns and Guidelines
Package Related Patterns Together*, Pattern Packaging*, Provisionable Pattern Implementation*, Use an Asset Repository (Chapter 16)
Use Models in Documenting Patterns
Summary
How can we improve and simplify the documentation regarding the details about the design and use of a pattern? Provide visual models that detail a pattern and how to use it. As we’ve seen in the creation of other software solutions, the use of visual models is a proven and effective mechanism for communication and education.
Introduction
A number of groups within the organization need to understand details about patterns. These needs range from simple to complex and cover the design, implementation, and use of patterns. How can we improve and simplify pattern documentation? As we attempt to answer this question, there are a number of considerations to keep in mind:
• We need to understand how to create models and diagrams effectively. There are many options for diagram types and the information that we include.
• Not everyone prefers visual communication.
• Consistency in modeling languages reduces learning requirements and can make communication easier.
Explanation
Create visual models that provide details on a pattern and how to use it. As we’ve seen in other software solutions, visual models are a proven and effective communication mechanism.
Because we need to support multiple audiences with documentation, we need to keep these audiences in mind as we create visual models. Each audience will be looking for different information. We can create a single model with multiple perspectives and then publish as appropriate to the specific audiences.
In addition to targeting our diagrams to the audience, we also need to target diagrams based on the best way to represent the pattern. When it comes to visual representations, there is no one-size-fits-all solution. For instance, with UML we see that there are many diagrams, each with a specific purpose. Is our goal to convey information about the structure of the pattern? Are we looking to provide details on the behavior of the pattern? As we answer these questions, we can continue to dive deeper into specific types of diagrams that highlight some important aspect of the pattern.
There are a number of approaches that we can take to model pattern definitions and pattern instantiations. Samples of these approaches are provided in the Communicate Design with Patterns guideline.
Related Patterns and Guidelines
Communicate Design with Patterns (Chapter 16), Document Pattern*
Summary
The focus of pattern packaging is taking the steps necessary to make the pattern as easy to find, install, use, and update as possible. We need to ensure that we are reducing or eliminating as many hurdles as possible for those who wish to reuse the pattern. Old habits and culture tend to guide people toward reinventing solutions rather than reusing existing solutions. We need to remove as many excuses as possible for not working with these reusable assets. We need to support the pattern as a reusable asset. We might create the world’s best and most important pattern, but it has no value if we don’t support its consumption by others; it may as well have never been created. This is part of the discipline of PBE; we need to follow through and go beyond just creating a technical solution.
We also need to recognize that a pattern does not exist unto itself; it’s related to other artifacts. Patterns do not exist in isolation; they are related to requirements, other patterns, DSLs, profiles, and model templates. As part of the effort to support reuse, we need to be aware of these relationships and make the user community aware of them.
All in all, we need to ensure that we are making it as simple as possible for Pattern Users to find, access, and install the patterns. The challenge that should be left for users is figuring out how to apply the solution in their situation. Anything that distracts from that focus is a shortfall in our efforts in building and providing the pattern.