Authors: Katie Levy & Ashley Hayes
Editor: Rachel Bryars
Documentation is one of the most overlooked — and critical — components of any Salesforce effort. When it comes to saving time, building efficiently, and quite simply, making sure your Salesforce org stays functional as new changes are introduced, documentation is crucial. Whether you are an administrator with a requirement to delete a field, a developer trying to update existing code, or a consultant trying to understand an existing org you’ve been assigned to modify as part of a project, knowing what metadata exists and why is essential.
Without robust documentation, including the “what” and the “why” of the metadata in your org, organizations risk breaking existing functionality with every change made. And as new employees join the organization, it can be time-consuming, if not impossible, to get up to speed.
At HigherEchelon, we are our own best Salesforce customer. We use Salesforce internally to manage everything from recruiting, hiring, new employee onboarding, and training to project management, business development, and much more. But our org is no exception to the documentation rule; as we evolve as a company, so must our Salesforce org, and documenting it is critical.
That’s why when HigherEchelon welcomed our two Hiring Our Heroes fellows this summer, we asked them to develop a technical design document (TDD) for an internal application we created in Salesforce.
Since 2020, HigherEchelon has been a proud partner of Hiring Our Heroes, an organization dedicated to connecting the military community with employment opportunities.
The Value of TDDs
With every release, our own Salesforce org becomes even more complex, and as we work to update everything from fields to flows to improve our employee’s user experience, understanding the “what” and the “why” of every piece of metadata is critical. That’s why we believe strongly in the value of tools such as technical design documents.
HigherEchelon’s Hiring our Heroes Fellows worked to build a TDD for HigherEchelon’s Project Management App, released internally this year. The documentation ensures that team members understand the “what” and the “why” of every piece of metadata within the app, and will help ensure enhancements made to the app are made thoughtfully (and, without breaking anything!).
A TDD is typically written by the team developing the solution and describes the entirety of the design in detail. Design elements such as the data model, the security model, user permissions, report types, and much more are included. HigherEchelon’s Hiring Our Heroes Fellows not only gained valuable insight into the inner workings of a brand new app in our internal org, but also helped provide tools to identify the impacts of any change, large or small, to our Salesforce org in the future.
Benefits of Documentation
For many organizations, documenting release change is not a priority, but we know firsthand how critical that is to the health of any Salesforce org. By taking the time to document, we can:
- Save time by enabling out internal teams to see where metadata is used and why, ensuring when it’s time to make an update, they aren’t left asking, “what is this, where is it used, and what will changing it impact?”
- Prevent negative impacts of code and configuration changes by ensuring our internal teams can easily understand how different pieces of metadata interact with each other.
- Proactively suggest enhancements based on existing functionality.
“As a new member of the HigherEchelon team, working on the technical design document (TDD) for HigherEchelon’s Project Management App allowed me to learn quickly the “what” and “why” for the application. Documentation records the growing complexity of the application and functions as an effective training tool in bringing a new team member, like me, up to speed on the organization and internal procedures of the company.”
— Stephanie Maenza, Hiring our Heroes Salesforce Fellow
“Working on the TDD for HigherEchelon’s Project Management App, I gained valuable insight into how important proper technical documentation is for an organization. Taking the time to provide the “what” and “why” not only allows for better continuity, but it also helps an organization plan effective future implementations and changes that do not disrupt the current framework.”
— Geralyn Hall, Hiring our Heroes Salesforce Fellow
Contact HigherEchelon for Proven Salesforce Implementation Services
Curious about our approach to technical documentation? Have questions about how to best document your org? Are you looking to implement Salesforce at your organization and want to ensure proper documentation procedures are followed? We’re here to help!
Client Review: 5/5 ★ ★ ★ ★ ★
HigherEchelon has been a wonderful partner as we launched and customized our SF platform with them from cradle to grave. They are always ready to support our needs and find the best solutions to meet our needs.
– Public sector client, AppExchange review