Styleguide and Architecture Principles
Some time ago style guides were popular. In the Internet you can still find some of this offers. Users ask today about it.
We offer three documents for help and Guidance.
- The Style Guide
- Modeling Guidelines
- Governance Rules
All three documents help to model and ensure consistency in modeling. The first prerequisite for it is an understanding of the roles of the involved project staff. Not every rule in the documents addresses every project member
- The Style Guide regulates how we use notations and descriptive means. We restrict standard notations. It gives examples and defines modeling patterns. But it regulates simple facts, such as the color scheme too.
- The Modeling Guidelines give guidance on what to do, explain working techniques and apply soft skills.
- The Governance Rules ensure conformity and timeliness of the models. Many games and "ceremonies" play a role here.
A base are architectural principles. Architectural principles set the framework for the three documents mentioned above. TOGAF® gives examples for such principles and emphasizes that a common project should have not more than 20 architectural principles. Here are examples of my architecture principles. They are used as the foundation for Style Guide, Modeling Guideline, Governance Rules.
|Separation of Concerns||Different concepts are shown separately.
One example is the separation of BPMN / CMMN process models and the description of business logic models with DMN or TDM. Models with different release cycles are separated and organized into multiple models.
|Refinement||Refinement, adding details, logical relationships support the principles of "separation of concerns" and "structuring / limiting the scope" of models.
The refinement and "Adding Details" is used within a perspective only (since this establishes a parent-child relationship). In case of relationships between perspectives, "Logical Relationships" or "References" are used.
|Logical Relationships / Reference|
|Structuring||The repository is structured.
Models are represented for different abstractions and on different levels of detail.
The naming of the abstraction levels expresses the intended purpose.
|Structuring/Limitation of size||The size of each model is limited. The number of elements depends on the selected notation and the level of detail.|
|Common Vocabulary / Definitions||A Common Vocabulary defining the used terms is used. The vocabulary is used for a consistent naming convention too. The vocabulary is defined and used across projects.|
|Use of Colors||Color tags for identifying attributes (e.g., priorities) are used sparingly. Legends explain the meaning of such colors|
|Reuse / "Single Source of Truth"||Model elements and models are reused. Redundant descriptions of model elements must be avoided.|
|Collaboration||Models are created collaboratively and shared across the enterprise.|
|Stakeholder orientation||Models serve stakeholder needs. The content of the models must be rich enough to fulfill the tasks of the stakeholder. Proven means of representation are preferred.
Outputs are designed in form, structure, and content according to the needs of the stakeholders
As always I'm happy about any feedback.