Introducing Salesforce Diagrams
Architects design systems and processes to keep up with the speed of business. Diagrams are an essential tool used by architects to align stakeholders on their vision and help delivery teams understand the details of an implementation. We found a couple problems with the state of Salesforce diagramming today that challenges an architect’s ability to do this effectively.
- There are several languages such as the Unified Modeling Language (UML), the Architecture Description Language (ADL), SysML, and more that attempt to unify and simplify architectural diagrams. Architects have abandoned many of these languages and supporting tools in an effort to be more agile.
- A quick search for “salesforce architecture diagrams” produces hundreds of ad-hoc, outdated diagrams and static images requiring architects to start from scratch every time. Without a framework to approach the creation and communication of Salesforce diagrams they often become overly complex and packed with details that overwhelm the viewer.
We released a set of resources on the Architect Digital Home to help you organize, create and communicate diagrams with a distinct, predictable, cohesive look and feel. This post gives an overview of the new approach to architectural diagrams we’ve built at Salesforce, how we landed on this approach, and what you can do today to get started building diagrams in ways that are faster and easier to understand.
A new approach
As the most trusted digital advisors in the Salesforce ecosystem, your diagrams need to be accurate and understandable to effectively align teams and stakeholders. Being clear on the intended audience and purpose of your diagram can make it easier to determine the level of detail.
Styles communicate purpose
We categorize diagrams into two general styles, based on purpose and intended audience. This is the first and most important step because handing a data model to your CEO to communicate the business value of your solution or a capability map to your delivery team will cause confusion and waste cycles.
- Marketing, Strategy & Sales — Answer “Why we are doing this?” by communicating the capabilities and products driving the business value being delivered by your solution. These diagrams help business stakeholders and technical influencers understand business processes, capabilities, and the vision for a solution.
- Documentation & Implementation — Answer “How are we doing this?” by communicating the functionality of your solution with an implementation ready view. These diagrams help technical stakeholders and delivery teams understand how to implement the solution and product related technical detail.
Choosing between the styles should be pretty straightforward, once you really think about the purpose and audience.
Levels communicate details
The real value in this approach is abstracting the level of detail to only what’s needed to help your audience clearly and effectively understand the key concept being communicated. Diagram levels help you efficiently communicate with the appropriate level of detail for the right audience. As you move from Level 1, “The Big Picture”, to Level 4, “The Double Click”, you zoom into greater levels of detail, finer granularity and reduced complexity.
The resources on the Architect Digital Home will guide you through the appropriate scope for each level along with different types of elements to include. Go with your instinct when selecting the level. If you feel like you’re combining concepts or overloading the diagram then you probably are. Selecting the right level for your diagram helps you communicate with the right amount of detail, which means even highly complex diagrams can still be easy for a viewer to understand.
How did we get here?
One way to understand the experience for architects working in the Salesforce ecosystem prior to this new approach is to imagine a developer working on Salesforce with no developer guides, documentation, and with no CLIs or IDE extensions. Last year we asked architects and others in the Salesforce ecosystem for feedback about what it’s like to work with Salesforce diagrams through a series of surveys and design workshops.
We asked: “What kind of diagrams do you spend most of your time building?” Here’s what you told us:
“Anything involving iconography — please make all the icons for things more readily available!”
We received over 800 responses across two surveys that helped us understand the tools and workflows architects use to create diagrams. We gained a ton of insight into the challenges and priorities architects face when delivering these artifacts. The feedback was clear and consistent.
- Architectures had inconsistent levels of detail & appearance
- There are no Salesforce-provided symbols, icons, or templates for the common diagrams architects create
- The landscape is fractured and siloed
- There was no single destination for reliable, up-to-date resources
We also conducted several workshops with architects, solution engineers, designers, technical writers and other experts across Salesforce. Before the workshops, participants shared diagrams that were relevant to their daily work. We used these samples to explore how different stakeholders organize, talk about and use diagrams.
We built our approach from the feedback we heard from practitioners across the Salesforce ecosystem, as well as our internal stakeholders. We saw that diagrams are used for a wide variety of conversations with a wide variety of motivations. We adopted the idea of diagram styles because we decided it was important to start by being clear and prescriptive about the purpose of diagrams. We also saw that the purpose was often lost on the viewer because folks tended to overload diagrams with very different kinds of details. We adopted the concept of levels based on the C4 model as an “abstraction-first” approach to to make this all easy to learn and use.
We partnered with our amazing Design Systems team to create a standard for architectural elements suited to the Salesforce technical landscape. And, we engaged our graphic artists, product architects, and engineers to reimagine Salesforce product data models and ERDs in this new standard. We are excited for you to see the result of that effort very soon! We know it’s long overdue.
What you can do now?
Get started creating your own diagrams with the Diagram Resources and Templates and Kit of Parts on the Architect Digital Home. We released this guidance and initial, simple templates to lay the foundation of this approach. Use these resources to help you organize, create and communicate diagrams with the distinct, predictable, cohesive look and feel that has been missing.
You can also review past Trailhead Live Sessions complete with “How to” videos and slides covering these resources and templates. Today each template can be downloaded to Powerpoint or copied to Google Slides to start working on your own. And yes! we are planning support for other popular tools in the near future. Bookmark our TDX21 session, Introducing Salesforce Diagrams, to see the roadmap for diagrams including tooling announcements. We are equally excited for that!
We are also focused on producing more architecture diagrams for you in the Reference Architecture Gallery, along with a wealth of other resources to help you create diagrams easier and faster with this approach.
And, of course, follow @SalesforceArchs and Salesforce Architects on LinkedIn for all the latest updates on this initiative and more.
