Has anyone used Diagrams to store their company-specific documentation? Such as standards and guidelines for using fact sheets?
Solved
Using Diagrams to store documentation?
Best answer by Paco Quiroz
Hi Kathy!
We created a “Building Block” Factsheet type to store information of Architecture Patterns for reuse in solution design.
The Factsheet has information regarding applicable use cases for the pattern, as well as the relationships to IT Components, Tech Categories, Applications and interfaces it uses.
There are two subtypes of Building Block (per TOGAFs definition): Architecture Building Block, for Logical Patterns (mostly Tech Categories) and Solution Building Block, for Physical Patterns (IT Components, Interfaces, Applications).
We use the Resources tab to store links to any documentation (either links to existing URLs, or documents) and diagrams (in FreeDraw).
For more general documentation, Architecture Guidelines & Standards we keep links to other documentation sources, via links and uploaded documentation. Linked to an EA Objectives Factsheet.
Hope this helps.
Paco
We are setting up a new unique factsheet type to house architectural standards. The reason we are doing this is so that we can relate the standard in question to an application to call out exceptions if those standards are not being met.
We are using diagrams to create decision tree rubric documentation to show how people should apply reasoning for fields such as Technical Fit or Functional Fit.
We use the resource link on the factsheet to tie to additional information about the application, project, or other.
Hi Kathy!
We created a “Building Block” Factsheet type to store information of Architecture Patterns for reuse in solution design.
The Factsheet has information regarding applicable use cases for the pattern, as well as the relationships to IT Components, Tech Categories, Applications and interfaces it uses.
There are two subtypes of Building Block (per TOGAFs definition): Architecture Building Block, for Logical Patterns (mostly Tech Categories) and Solution Building Block, for Physical Patterns (IT Components, Interfaces, Applications).
We use the Resources tab to store links to any documentation (either links to existing URLs, or documents) and diagrams (in FreeDraw).
For more general documentation, Architecture Guidelines & Standards we keep links to other documentation sources, via links and uploaded documentation. Linked to an EA Objectives Factsheet.
Hope this helps.
Paco
My customers typically use the 'Resources' feature to link company-specific documents to a SharePoint site. They also reference the diagram for Enterprise Architecture process-related visuals. Please see 'Store Resources' on fact sheets.
We have extended the meta model with two new fact sheets type. One is Architecture Principles that can be related to Applications and IT Components - we can then visualize (report) the level of alignment. Second we have added Architecture Decisions Records (ADR) - we document Architecture Decisions inc. rational, options, alignment with our principle's, impact etc. We also encourage people to use the 'Resources' feature to link company-specific documents to a SharePoint site, DevOps etc.
We keep documentation artifacts out of 3rd-party SaaS services such as LeanIX, Monday.com, etc. Instead, we refer out to a central document service that is much more robust.
For LeanIX specifically, diagrams are in the NG editor. Other documentation is linked out to Confluence wiki pages or to SharePoint Online. These platforms offer version control, eDiscovery, full text/enterprise search, data classification, etc.
Hi Kathy!
We created a “Building Block” Factsheet type to store information of Architecture Patterns for reuse in solution design.
The Factsheet has information regarding applicable use cases for the pattern, as well as the relationships to IT Components, Tech Categories, Applications and interfaces it uses.
There are two subtypes of Building Block (per TOGAFs definition): Architecture Building Block, for Logical Patterns (mostly Tech Categories) and Solution Building Block, for Physical Patterns (IT Components, Interfaces, Applications).
We use the Resources tab to store links to any documentation (either links to existing URLs, or documents) and diagrams (in FreeDraw).
For more general documentation, Architecture Guidelines & Standards we keep links to other documentation sources, via links and uploaded documentation. Linked to an EA Objectives Factsheet.
Hope this helps.
Paco
Hi Paco, interesting post, we are doing something similar (to support integration modeling), but thinking on extending it - can you elaborate some more on “Budling Blocks”, example etc.
Thanks
//Thomas
+1Hey
Hello,
Let me provide some context first.
The goal of the Building Block Factsheet is to assist Solution Architects in leveraging the available Factsheet information (Applications, IT Components, Interfaces, and Data Objects) to create Solution Architectures using preexisting and standard patterns.
To begin, we have grouped IT Components into "Technology Domains" such as Integration (Mulesoft, SAP PO, API Gateways) or Data Analytics (PowerBI, QlikView, Tableau, Data Bricks). Each Technology Domain is represented by the Technology Category Factsheet type, which may have a hierarchical structure. For example, the Integration Technical Domain may have Technical Capabilities like API Management or Microservice Management as parent-child relations. We have our own Tech Category taxonomy to organize this structure.
For each "Technology Domain," we have identified Patterns such as Publish and Subscribe, API Management, and ETL Integration Patterns. These Patterns serve as an "accelerator" for Solution Architects to create their artifacts. To document these Patterns, we have created a Factsheet Type called "Building Block," inspired by TOGAF. It has two subtypes:
1. Architecture Building Block (ABB): This subtype is related to a Logical Architecture view, focusing on the Technical Capabilities required to enable the Building Block. The ABB Factsheet subtype has relations to Tech Categories and Data Objects only.
2. Solution Building Block (SBB): This subtype is related to the Physical Architecture view and the implementation of the Building Block. The SBB Factsheet subtype has relations to IT Components, Applications, and Data Objects.
Each ABB can have multiple SBBs because there can be multiple possible solutions to implement a specific integration, such as API Management. For example, one solution could use Azure API Gateway, while another could use Mulesoft's Anypoint.
The Interface Factsheet type has a relation to the Building Block Factsheet to identify the specific one being implemented.
Each Building Block Factsheet (ABB and SBB) has a group of attributes that describe the Use Cases in which the Building Block applies, prerequisites for implementation, and maturity level. The resources tab of the Factsheet contains links to diagrams (created in FreeDraw) that illustrate how the Building Block works. The ABB contains a Logical View, while the SBB contains the Physical View.
When creating a Solution Architecture, the Solution Architecture diagrams use the SBB Factsheet representation instead of the individual elements it contains. This approach allows us to simplify views, such as Single Sign-On Patterns.
I hope this clarifies the information.
Paco
Login to the community
No account yet? Create an account
Enter your E-mail address. We'll send you an e-mail with instructions to reset your password.