☏ 01494 590428 | ✉ hello@commerceworks.net

Document your Salesforce Instance

On one of my initial client meetings as a junior consultant I attended a meeting. My employers at the time were presenting the basics of IT project management to the client. At the start of the presentation the first bullet point was:

Document, document, document

And throughout the presentation the senior consultant repeated the point several times.

Roll forward more years than I care to mention and some of the most difficult meetings we have are with customers that have lost control of their Salesforce instance. It generally goes something like this:


We've had a series of admins and developers that joined the organisation then left. They fixed user issues and made functions work but now they've left and we're not sure what they actually did. To make life worse we've had some staff turnover with the key people that specified the changes and we've lost internal knowledge about exactly how Salesforce works.
The users are now scared of certain functions because they're not really sure what the system does and a little scared of the automations that'll send emails out to customers.


Do you have documentation for the work that's been done?



I can't emphasis enough what a wonderful system Salesforce is and how incredibly flexible it is. I also can't emphasis enough how any system, no matter how wonderful, will mess you up if you don't create documentation.

Very few people like to document IT systems. It's not exciting and you generally feel as soon as it's published you need to change it. That's quite often true and all the more good reason to do it.

There are broadly 2 types of documentations that you need to cover, admin and end user. I'll cover off both below.

Admin Documentation

As the title suggests, the Admin documentation covers everything required if your Admin wins the lottery and never comes back to the office. From day 1 there are a few principles to follow:

  • Use the description fields in Salesforce. Throughout the configuration of Salesforce there are description fields. These allow you describe the purpose of a field, workflow, validation and everything else. Most half-decent admins will be able to follow and figure out configuration but why make someone do that ? Use the description fields to clearly outline what you're doing and why. Fields that get populated by workflows are a great example. When looking at the field it won't be obvious to another admin exactly how the field gets populated so use the description to help them. Yes, it takes a little longer to use description fields and you're never particularly motivated when you're busy but please folks, just do this one, for all of us that follow your work.
  • Configurations and custom objects. More complex Salesforce instances can have multiple record types, page layouts and custom objects. Write down all of these and their purpose.
  • List integrations, third parties and contacts. Write a secure document with details of anything involving third parties and the passwords and account details. If anyone configured something take a note of their contact details, what they did and when they did it. They may have move employers but Linkedin makes it very easy to find most people.
  • Code. Apex code can be followed but it's a painful process. Everyone writes it differently and code reviews are expensive exercises if not completed at the time of writing.  I recommend a separate document with all Apex described in plain and simple language including the intended purpose. Flow charts are particularly useful here to show how the code effects the system. 

Please note, getting a tool to list all config tables in an Excel spreadsheet doesn't represent good documentation. I've seen this recently, the client thought their instance was documented and the consultant got 3 days of billing for it. Don't fall for this one.

End User Documentation

How many end users memorise their Salesforce training ? If you're not certain, it's a low number and they often need something to help when unsure. Good end user documentation is even rarer than good admin documentation and your users need it.

All documentation needs to be clear and concise, end user documentation needs to be clearer and conciser than the rest if it. Not too wordy, lots of screenshots, arrows and clear descriptions about what's going on. I've used 2 tools that have worked for me in different instances.

Powerpoint clickthroughs are extremely effective. Follow a process, slide after slide with screen shots, text to explain what's happening with pointers and red boxes to highlight the field in question. You can also use the speaker notes for more details.

Mediawiki involves more work due to the particular markup but provides a friendly way for users to find and use documentation. I use a series of tables with screenshots and descriptions to explain the process. As it's the software behind Wikipedia most users find it quick and easy to follow and you don't need to worry about a complex file directory.

There are plenty of other tools out there - we've recently converted to Quip and I think that would work well. Also look at Evernote and dedicated tools like Confluence from Atlassian.

In some cases I printed key documents and laminated so users could stick them above their desks. High level process diagrams work well here with (albeit) printed links to the electronic source material.

Sharpen the Saw

It's critical that documentation is a process not an event. Whenever you make changes to the product enter time into the plan with resources for documentation. I recommend all users to perform spot checks on documents to see if they reflect current functionality, it's amazing how quickly they get behind. Learn from users about which documentation is better than others so you can continually improve it.

A few concluding words about documentation

  • Start all projects with a mantra to produce great documentation.
  • If you didn't start your project with that mantra, assume your document is inadequate - review it and fix it.
  • Make all documentation clear and concise with enough detail. Use lots of annotated screenshots and descriptions.
  • Fixing the after effects of poor documentation can be expensive. Code reviews are long, alborious exercises to work out what's going on. We'll happily do one for you but we'd rather not.

☏ 01494 590428 | ✉ hello@commerceworks.net