Documenting the architecture of a Practice Framework is critical to making sure that key decisions are captured and communicated to the development team. Documenting the practice framework architecture involves defining and capturing the key guiding principles and a consistent approaches for structuring the framework, as well as documenting the key structural elements. 

In general, don't spend much time:

• getting the architecture perfect -- it can evolve over time as the individual method elements are defined and detailed. 
• providing detailed descriptions of the method elements -- just name and briefly describe the elements and enter a few outline details if it helps to more clearly describe the element's basic definition.

Note: While documenting the architecture is important, it is not enough to just define it on paper. It is important that the architecturally-significant method elements be actually built using your selected method implementation environment.

When documenting the architecture, there are two key decisions that you need to make: what to include in the architecture description and what level of detail. Each of these are described in the following sections.

Architecture content

The architecturally-significant method elements in a practice framework are the following:

• Practices
    
• Core elements: Elements shared across practices:
• • Work Product Slots: Information that passes between the practices
  • Common method content elements (especially, roles, guidance, work products): Definitions that are shared across practices
  • Common standard categories (especially domains, disciplines, work product kinds, role sets, tools)
  • Common custom categories
     
• Practice Configurations: Assemble practices into usable methods for practitioners

The following are some examples of the types of decisions you might make (and document) when architecting a method framework:

• Use a Delayed Assignment approach for role assignments and standard category assignments (except for tools) in order to improve the flexibility and configurability of the framework
• Use a specific set of method plug-in and method configuration types in order to provide a consistent approach for structuring the framework. We recommend the plug-in types defined in Concept: Practice Library Plug-In Types and the configuration types defined in Concept: Practice Library Configuration Types.
• Follow a consistent set of naming conventions. We recommend the ones defined in Guideline: Method Element Naming Conventions. 
• Provide recommendations and constraints for the following:
• • How navigation view should be built
  • How standard categorization should be handled (as well as any common standard categories)
  • Approach for assigning roles (as well as any common roles)
  • Approach for scaling elements
  • Approach for associating guidance
  • Approach for dividing the architecture into smaller chunks to reduce complexity

Level of detail

There is a range of options for the information that can be captured in an architecture description. In some cases, where there is an architectural decision to be made, there are a set of architecture notes that are written up proposing what to do, discussing all the choices and the tradeoffs that have been made. These notes can be an email thread, a forum thread, or a wiki. Then, the final decision is captured in an architecture document. The notes serve as a historical record of decisions (if you keep them) and not a polished, maintained view of the architecture. The maintained architecture document is a separate work product that is mainly targeted at new developers and maintainers of the system, and to ensure the architecture does not degrade. The notes get filed in a notebook for later reference in case people are curious why the team did something.

In summary, the following are the range of options for the architecture documentation:

1. Keep a set of notes that are a historical collection of architecture notes that are not maintained
2. Keep a set of notes, plus define a high-level overview of the architecture
3. Keep a set of notes, an architectural overview, plus a set of distilled key decisions
4. Keep a set of notes, an architectural overview, a set of distilled key decisions and a set of evolutionary models
5. Keep a set of notes, an architectural overview, a set of distilled key decisions and a set of formal models at different levels of abstraction

For each project, it is important to decide which of the above options makes the most sense.