Content last updated July 2022.
Read about our update schedules here.

Introduction

Simple solutions follow the most direct path in engineering. Simple architectures are clear, are easy to read and understand, can be maintained effectively, and are planned and delivered with intention.

Simple architectures fulfill business requirements using technology choices that are easy for delivery and maintenance teams to work with, without added features or complications. Systems architected to be simple are easy to own, maintain, and evolve because they follow clear and consistent implementation patterns. Builders can interpret and implement designs for new features, and maintenance teams can understand documentation of what’s been implemented. Systems architected to be simple evolve and age gracefully, as features and fixes are planned for and prioritized for delivery in terms that are transparent to business and technology stakeholders alike.

You can make your systems simpler by focusing on three key habits: readability, maintainability, and intentionality.

Readability

At its core, the concept of readability is about creating consistency that makes it easy for people to understand how things work. Readability aligns delivery and maintenance teams, and helps people who are unfamiliar with the system quickly understand how pieces fit together. It means your team can be less dependent on individual people with institutional or historical knowledge to effectively onboard vendors or new team members. It means skilled individuals on a team can focus on the quality and trade-offs of the choices being made, because the system’s configuration and code are easy for humans to read and understand. Readability can speed up governance and quality assurance processes, and help teams better identify when they might be creating redundant customizations. It can also boost the chances of having a system that behaves in ways that are reusable and testable.

You can increase readability via effective design standards and documentation.

Design Standards

Design standards provide guidance to keep all customizations consistent, even at the earliest stages of development. Design standards act like guardrails, keeping all delivery teams and maintenance teams working on your system aligned on how to approach and implement customizations. Defining design standards helps boost the productivity of your delivery and maintenance teams, makes code and architectural reviews easier to conduct, and provides a basis for better documentation.

Without design standards, teams are more likely to work in silos. Without the coherence that design standards provide, businesses will find themselves struggling with:

A key benefit of design standards stems from the conversations and decisions stakeholders must make to create them. Specifically, the process gives your business and technology leads the opportunity to align around what optimal design looks like for your business.

Include the following in your design standards

Along with defining these standards, you’ll need to decide how and where to maintain and store them. If teams across your company can’t find your design standards (or aren’t even aware they exist), they won’t be effective. Ideally, your design standards live within the same system as your documentation (see the next section for more).

The list of patterns and anti-patterns below shows what proper (and poor) design standards look like for a Salesforce org. You can use these to validate or improve your design standards.

To learn more about Salesforce tools that can help you define design standards, see Tools Relevant to Simple.

Documentation

Documentation explains the what, how, and why of your system. Without meaningful and consistent documentation, teams waste a lot of time trying to understand the system as it is (and potentially misunderstanding features and customizations).

Good documentation takes time to create. While most teams agree that documentation is important for large projects, it can be a tempting step to skip when making quick changes like configuration updates or minor tweaks to an automation. Not documenting the changes you make to your system is always an anti-pattern. Skipping documentation may save a small amount of time upfront, but the amount of time required to troubleshoot an org that isn’t properly documented will more than cancel out those time savings. Always include enough time to create documentation in all of your estimates, regardless of the level of effort required for the updates you’re planning to make.

The lack of clear documentation can lead to a variety of problems, including:

For Salesforce solutions, maintain documentation for:

Develop a set of documentation standards to ensure that all current and future team members will be able to interpret documents the same way. (design standards can help with this.) It’s also important to consider how users will be able to search documentation to find relevant sections or terms. As your system ages and grows in complexity, your documentation will also grow. The usefulness of the information in your documentation will be directly related to how often, how quickly, and how easily users can search for and find relevant items.

The list of patterns and anti-patterns below shows what proper (and poor) documentation looks like for a Salesforce org. You can use these to validate or improve your documentation strategy.

To learn more about Salesforce tools for documentation, see Tools Relevant to Simple.

Readability Patterns and Anti-Patterns

The following table outlines patterns to look for (or build) in your org as well as anti-patterns to avoid or target for remediation.

Patterns Anti-Patterns
Design Standards In your org:
- Code and declarative customizations have consistent, human-readable names
- Data models have consistent, uniform names for objects and fields
- Audits show fields are consistently filled out and referenced in reports, etc.
In your org:
- Code and declarative customizations do not have consistent names
- Data models have inconsistent names and many objects and fields seem to be redundant
- Audits show many unused fields or various levels of usage, and there is no consistent link to reporting, etc.
Within your business:
- Teams know what tools to use (and not use) to get work done
- Approved design patterns are easy to find and identify by use case
Within your business:
- Teams use many different tools to get similar work done
- There are no approved design patterns
- It takes a lot of time for vendors or new employees to onboard
Documentation In your org:
- Code and declarative customizations have clear descriptions
In your org:
- Code and declarative customizations do not have descriptions, have descriptions that are difficult to understand, or have descriptions that don't seem to match what the customization is actually doing
Within your business:
- Diagrams for business capabilities and technical implementation details exist for all solutions
- Key who/when/what information logs exist for code and declarative customizations
- People can search for and find relevant documentation
Within your business:
- The what/how/why of solutions is hard to find and may be unavailable to most teams
- People struggle to understand solutions and the system they are working with
- It takes a lot of time for vendors or new employees to onboard

Maintainability

Maintainability means a system can be kept in a healthy state, with new features moving into and technical debt moving out of the system on a regular, predictable basis. Maintainable systems enable your teams to deliver value to the business with predictable speed and quality. The maintainability of a system depends on several factors, including how readable it is, how loosely coupled it is, and how thorough its testing strategy is.

Most importantly, the maintainability of a system depends on the straightforwardness of its design. This section covers ways to create more straightforward solution designs, and increase maintainability.

You can build solutions that are simpler to maintain by focusing on two keys: using standard over custom functionality and handling technical debt.

Standard Versus Custom Functionality

Salesforce offers a range of prebuilt solutions — Sales Cloud, Service Cloud, and many Salesforce industry solutions — as well as the flexibility to create your own custom solutions. The foundational services that power Salesforce’s own cloud solutions are also available to any custom solutions built on the Salesforce Customer 360 Platform. Use the prebuilt services and solutions from Salesforce as a trusted foundation for as many of your solutions as possible.

Using prebuilt platform services has two distinct benefits. First, your apps naturally benefit from the latest Salesforce innovations with every release. And second, your development teams can focus on expanding and deepening the business capabilities provided by your Salesforce solutions rather than handling basic architectural heavy lifting.

Properly choosing when to use standard functionality and when to build custom functionality isn’t challenging from an architectural point of view. The keys are:

It is that simple. As you can see in the patterns and anti-patterns below, the anti-patterns boil down to replicating standard features in a custom solution, or using more complex technology to deliver customizations.

In practice, you may encounter a scenario in which a custom functionality anti-pattern is viewed by business stakeholders as the best or only viable way forward. In these instances, it is essential that you explain to the stakeholders the trade-offs involved in choosing this path and then thoroughly document the decision, its rationale, and its implementation. This is also an area where delivering core value early and adapting over time can help your stakeholders better understand the best way forward.

To learn more about Salesforce tools that can help you increase maintainability, see Tools Relevant to Simple.

Technical Debt

Technical debt is a natural part of any system. Yesterday’s sound designs can become anti-patterns when technology or business needs change. Maybe something built to fill a gap in Salesforce platform functionality suddenly becomes redundant with a new Salesforce release or product launch. Perhaps a more performant or flexible technology supersedes a technology you’ve already implemented. Technical debt can be created in many ways.

A key benefit of building applications with the Salesforce Customer 360 Platform is the backwards compatibility built into the platform. This means that new platform innovations may change the pattern you should use for solutions moving forward, but the everyday function of solutions you’ve built on previous Salesforce technologies will continue to work. Over time, any solution based on older technology will begin to pose risks or bottlenecks for adding new features into your apps, and lower overall solution health.

Planning for and carrying out regular work to address technical debt is essential to maintaining healthy, straightforward designs in a Salesforce solution. Failing to plan for, audit for, and remediate technical debt is a sure way to create a system that is poorly architected.

One way to minimize technical debt is to avoid introducing it as much as possible, by avoiding shortcuts and by preferring standard functionality over custom functionality. Shortcuts, like hard-coding values, may be tempting to save time, but in the long-term they create debt that must be repaid.

The keys to addressing technical debt from an architectural perspective include:

The difficulty can be getting stakeholders aligned with taking action. Some stakeholders may perceive on-going maintenance as addressing “yesterday’s mistakes” or taking away from the features they want their budget to support.

Showing the real business impacts of action and inaction, along with clearly defined deliverables and timelines can help your stakeholders understand the value and relative priority of addressing technical debt. Consistently doing the work to connect technical debt to business impacts won’t just help your stakeholders to better understand the work to be done. It will also help you ensure you’re identifying and addressing technical debt in ways that truly benefit users.

The list of patterns and anti-patterns below shows what proper (and poor) technical debt management looks like for a Salesforce org.

To learn more about Salesforce tools that can help you with technical debt, see Tools Relevant to Simple.

Maintainability Patterns and Anti-Patterns

The following table outlines patterns to look for (or build) in your org and anti-patterns to avoid or target for remediation.

Patterns Anti-Patterns
Standard vs. Custom In your design standards:
- There is a clear guiding principle to keep solutions from unnecessary customization
- The guiding principle for solutions uses the following priority: 1. Use built-in platform services, 2. Consider AppExchange apps before building a custom solution, 3. Use low-code customizations before writing code
In your design standards:
- Design standards either don't exist or don't have a clear rationale for avoiding unneeded customizations and code
In data models:
- No objects have names or functionality that duplicates standard objects
In data models:
- Objects duplicate the names and/or functionality of standard objects
In LWC, Aura, or Visualforce:
- No code exists to override standard page view mechanisms
In LWC, Aura, or Visualforce:
- Code exists to override standard page view mechanisms, often in the form of a single page app
In LWC, Aura, or Apex:
- No code attempts to override or circumvent the platform order of execution
In LWC, Aura, or Apex:
- Code attempts to override or circumvent the platform order of execution
Technical Debt In your roadmap:
- Work to address tech debt exists
- Deliverables and begin/end dates are clear
In your roadmap:
- No work to address tech debt is planned
- Deliverables are vague; begin/end dates are unclear
In your decision records:
- KPIs for pre-/post- tech debt remediation are clearly documented
- Trade-off discussions for action and inaction focus on business costs or benefits
In your decision records:
- Tech debt remediation has no measurable KPIs
- Tech debt is considered in technical or IT-focused terms, with no relevance to the business

Intentionality

Intentionality means systems are thoughtfully planned and delivered. It means delivery and maintenance teams have a clear view of the work to be done today and in the future, and everyone is aligned around the “why” of the work to be done. It means urgent requests can be triaged effectively and efficiently, and stakeholders can clearly understand the impacts and trade-offs of requests.

You can build intentionality via roadmapping and governance.

Roadmapping

A roadmap is a prioritized, validated, well-defined view of what's to be done. Effective roadmaps provide a clear picture of the business impact and technology impact of the work ahead. Engaging your business and technical stakeholders is a key part of roadmapping. Roadmaps enable you to get feedback and buy-in about the approach and outcomes before any work begins. Ultimately, roadmaps align every stakeholder about the “why” of work ahead.

If your team uses a backlog, it's important to understand your roadmap is not a summary or list of the items in the backlog. The relationship is the opposite: Items are only to enter the backlog if they can be clearly and credibly tied to a deliverable on your roadmap. High-quality roadmaps, created with the engagement of stakeholders, provide delivery and maintenance teams with a clear view of what they should focus on and how they should prioritize requests, making it easier to sort out conflicting requests and manage stakeholder expectations.

Poor or non-existent roadmapping leads to:

Stakeholders often need information that aligns to their roles in order to make decisions. Creating effective roadmaps requires a clear understanding of your audience and the type of information they need. Roadmaps are categorized into two styles to support business and technical audiences. Each style contains two levels of granularity to support different types of information.

Business roadmaps help stakeholders plan for organizational change, capitalize on growth opportunities, and stay aligned on corporate objectives. Business roadmaps also provide a way to ensure that IT spend aligns to the overall business vision.

Technology roadmaps help technical stakeholders with budget and resource allocation planning. They also help implementation teams understand where their projects fit as part of a bigger overall picture and identify any cross-team dependencies.

Make sure your roadmaps contain realistic timelines. A common mistake is to include only the amount of time it will take to implement a system without also considering the amount of time it will take to complete related activities. This can result in over-allocation of implementation team members and longer than anticipated delays. When creating a roadmap, account for the time it will take to complete the following:

Business and technology roadmaps that are well aligned communicate a holistic view of when capabilities will go live and what technology is behind them. The list of patterns and anti-patterns below shows what proper (and poor) roadmaps look like for a Salesforce org. You can use these to validate or improve your roadmapping strategy.

To learn more about Salesforce tools that can help you with roadmapping, see Tools Relevant to Simple.

Governance

Governance is the structure you use to handle prioritization, decision-making, and change management with your stakeholders. Governance makes it clear how decisions are made and communicated. It provides consistent ways for feedback and requests to enter into the decision-making process, and for all stakeholders to understand the status of maintenance and development work. Governance helps release management processes to be clear and consistent, and helps all team members understand their roles and responsibilities.

Without proper governance, teams will experience a variety of issues, including:

Perhaps the clearest sign that a system doesn’t have effective governance is slow and cumbersome releases. It’s important to recognize that the size of a governance system is not a measure of its efficacy. In fact, elaborate systems for governance (like those found in many large enterprises) can throttle the speed and frequency of releases.

Good governance is about making it hard for bad customizations to get past the early stages of development, and getting good customizations into production predictably and consistently.

Too often, governance efforts are reactionary. They are initiated or redoubled when an issue, such as excessive technical debt, starts becoming a business problem. In many cases, the unfortunate response is for the business to “lock down” development efforts and releases, instead of creating effective design standards and building automation to enforce those standards within developer tool chains and source control systems.

When building the framework for your Salesforce governance system include the following elements and consider these key questions to be answered:

The list of patterns and anti-patterns below shows what proper (and poor) governance looks like for a Salesforce org. You can use these to validate or improve your governance strategy.

To learn more about Salesforce tools available for governance, see Tools Relevant to Simple.

Intentionality Patterns and Anti-Patterns

The following table outlines patterns to look for (or build) in your org and anti-patterns to avoid or target for remediation.

Patterns Anti-Patterns
Roadmapping Roadmaps:
- Communicate information that's tailored to your audience (business or technical)
- Communicate information at the correct level of detail
- Show start and end dates
- Show prerequisites and dependencies
Roadmaps (if they exist):
- Are used as project kickoff materials and not artifacts for delivery
- Do not help align stakeholders and delivery teams
- Mix levels of detail (for example, by including systems and components within the same roadmap)
- Contain information that isn't tailored to their audience (for example, business capabilities and systems within the same roadmap)
Within your business:
- Stakeholders understand the "why" of work items
- Delivery teams know how to evaluate backlog items against longer term priorities
- Teams know who's doing what and how to manage dependencies
- Work is intentional, even when priorities have to change quickly
Within your business:
- Work is pulled from whatever is in the backlog and there is no clear “why"
- Teams have trouble coordinating interdependent work and often replicate work without realizing it
- Work is often reactive
- Stakeholders often feel frustrated and confused about what's being done and are usure when new capabilities will be delivered
Governance Within your business:
- Users can easily report bugs and request features
- The prioritization process for work items is documented and transparent to all stakeholders
- Environment strategy is clearly documented and development environments match the documentation
- Release planning is predictable and transparent to all delivery team members, and team members know who's responsible for what
- Releases are clear to users and delivery/maintenance teams
- Production support processes are clear and hot-fixes have a clear path to production
Within your business:
- Bug reports and feature requests are ad hoc- Work items have no clear prioritization
- Environments are provisioned ad hoc and may not be refreshed predictably; developers often do not have the environments and access they need
- Releases are unpredictable for delivery teams and users
- Hot-fixes are addressed ad hoc
- Your backlog has become an “idea bank” that is stale and stagnant
- Governance bodies act as a help desk that troubleshoots support requests
- Documentation is not easily accessible

Tools Relevant to Simple

ToolDescriptionReadabilityMaintainabilityIntentionality
ApexDocDocument Apex with static HTML pagesXX
Design PatternsExplore design patterns and templatesXX
Lightning Design System ValidatorValidate markup and see how to improve your codeXX
Project Management Tool by Salesforce LabsManage projects within your Salesforce OrgXX
Roadmap TemplatesExplore templates for roadmappingX
Salesforce Extensions for Visual Studio Code (Expanded)Analyze Salesforce code efficiently with Visual Studio Code ExtensionsXX
Salesforce Roadmap ExplorerExplore Salesforce product innovationsX
Setup Audit TrailTrack setup changes and audit historyXX

Resources Relevant to Simple

ResourceDescriptionReadabilityMaintainabilityIntentionality
5 Documentation Strategies to Improve Your Salesforce OrgImprove Salesforce implementation documentationX
Choose Naming Conventions (Trailhead)Learn how to apply naming conventionsX
Defining, Identifying, and Measuring Technical DebtDefine, identify and measure technical debtXX
Design Standards TemplateCreate design standards for your organizationXXX
Get Started with Salesforce DiagramsLearn how to create the right diagram for your use caseX
Getting Started with Coding Conventions (Treailhead)Define and follow coding conventionsX
How to Tackle Technical Debt (Trailhead)Manage technical debt in your Salesforce orgXX
Improve Your Apex Code (Trailhead)Apply basic principles of test-driven developmentX
Organizational Alignment (Trailhead)Learn the V2MOM process for alignmentX
Prioritizing and Planning a Way Out of Technical DebtForm a plan to reduce and remove technical debtXX
Salesforce Naming Conventions TemplateGet started with naming conventionsXX
Technical Debt: What Is It and Why Should You Care? Understand the impact of technical debt in your orgX
Using the Business Model Canvas in Enterprise ArchitectureCreate, deliver, and see value in a business modelX

Tell us what you think

Help us keep Salesforce Well-Architected relevant to you; take our survey to provide feedback on this content and tell us what you’d like to see next.