Top 5 reasons why you should document your Salesforce org

July 18, 2021

1. To make your job easier

  • With good documentation to reference, you’ll be able to make changes to your org faster and with more confidence (and make the right changes).
  • Let’s say for example a user from Marketing is asking for a new field to “score” a prospect.  You know from past projects that some other groups are also using scoring, but you aren’t sure if they are the same.  If you have good documentation, you can search for the other scoring fields and read about what the business use case was for these fields, the conversations that went on, and possibly even who requested these fields to be created.  
  • In this example, let’s say through reading the documentation for these fields, you realize that what the Marketing user has asked for is actually already built.  Without documentation, a meeting would have been called with the Marketing user, emails / meetings would have been required with other Marketing groups to understand their usage of the current scoring fields, and potentially in a worse case scenario, parallel duplicative functionality would have been built.  With documentation, all that is required is granting field access to the appropriate profile and perhaps some training.  

2. To ensure seamless scaling

  • If you have good documentation, it will be much easier for your org to scale, now or in the future.
  • Many times when an org is first being built, it’s for a particular business unit, and for a particular business use case.  But the power of Salesforce (and the significant investment a business must make), means that the tool is likely to grow quickly in an organization and can begin to encompass other teams and other processes.  If you are managing an existing org that’s more than a few years old, you are probably already at this place.
  • When an org begins to scale like this, and new teams and processes come aboard, the org faces new challenges.  Example questions that begin to emerge look like: are there any fields on the Contract object we can remove (to make room for a large project coming in)?  Should we use an existing Profile or create a new one? (for the new team coming into the system) Which record types on the Case object should support reps be able to see? (users are complaining they see unnecessary options when creating a new Case).
  • If you have good documentation across the org, the types of questions I laid out above should be answered pretty easily.  You will know why every field on the Contract object was created (and with some research, which ones might be able to be removed), you’ll know which Record Types were created for which business use cases over time, and you’ll have notes on who to talk to regarding Profile permissions (and who is the decision maker on what a particular team is / is not able to do in the system).

3. To easily onboard new Salesforce team members

  • Salesforce orgs can get very complex over time, and as they grow, the team managing the system usually does as well.  This can be additional admins, additional developers (perhaps from IT or other non-Salesforce specific domains), or even outside consultants who help manage your org.  What they all have in common is that when they walk into a new org, they need a ‘guide’ as to how the system is built and how it’s being used.
  • You can try to answer each question about the org as it comes up, but this is incredibly time consuming.  On top of this, an outside consultant or project based developer is usually only concerned with the one particular area they have been tasked with and not how that part of the system might affect other areas of the org.
  • If you have good documentation, you can simply share it with them.  A new team member can quickly come aboard and understand which objects are used most and how each team is using the tool.  A project based developer or consultant can understand a particular object / record type combination they will be writing custom code for, for example.  And all of this will happen much faster than if you had to sit down with each respective party and try to recall each important piece of information about a respective part of the org.

4. To help with user adoption

  • Like it or not, user adoption is a reflection of the team that is managing Salesforce.  Whether it was the team’s fault or not, if a new business unit spends time and money to develop a part of the system, and user adoption is very poor, it looks bad for the Salesforce team members.  Good documentation can help guard against this.
  • Good documentation forces you to put in words what a team wants and why they want it that way.  In addition to simply objects, fields, and other pieces a team might need, you should document what they need to do permission wise so you can be sure to have their Profiles set up properly.  Before you go live with a new team or process, you can refer to the documentation to ensure everything is working as you discussed in the various meetings, all the page layouts have the proper fields, and the right permissions have been granted so their experience is flawless on Day 1.
  • As a bonus, if there are issues during an initial roll-out, the Documentation gives you and the team a common place to reference and have a discussion.  You can put notes, chats, and other discussions right on the Profile or Object in question in order to resolve the issue quickly and get the roll-out back on track.

5. To make your boss happy

  • Whether your boss is a Salesforce architect, a Project Manager, the CTO, or even the CEO, they will be happy to see that there is some kind of source information explaining how the “magic box” of Salesforce works.  In a very short amount of time, your Salesforce org can become mission critical, and your boss will want to know that these mission critical processes are well documented.
  • From a practical standpoint, depending on what level your boss is at, the documentation may serve to: justify a certain budget for new projects, allow them to explain at a high level to their boss what the business is using Salesforce for, speak with authority in a meeting on whether Salesforce might be suitable for an extension into a new business unit, or maybe just give them peace of mind.
  • In addition to all of the above, having good documentation makes you look like a true Salesforce professional with all of your i’s dotted and t’s crossed.  Whatever the specific reason, your org being well documented will go over well with your boss and you’ll be better off for it.