January 2022

Inspiration

I’ve been thinking a lot about documentation in the last six months. Across the Salesforce ecosystem, people seem to agree that documenting a Salesforce instance is an ongoing challenge, and there aren’t many best practices or templates to follow. As I’ve worked on various bits of documentation recently, come up with a few guidelines that I think will stick for me, as well as a sample.

Break things into digestible chunks

Users and admins are most likely to read documentation when they’ve got a question. The easier it is for them to focus on the thing they’re currently interested in, the more likely they are to read and retain what you’re trying to get across. I’ve found myself writing documents around specific functionality – profiles and permission sets, or a particular automation.

Proceed from widely interesting to narrowly interesting

I’ve been trying to write documents that have beginning that would be useful and interesting to any Salesforce user, and assume that people will drop off as it gets more specialized. By the end, we’re deep in the weeds and only an admin would still be reading, but that’s okay!

Use screen shots

I’m sure you already know this, but it is incredibly easy to have conversation with users where you’re talking past each other. A screen shot is often the fastest way to be sure you’re both talking about the same thing.

Don’t just reproduce what is in Salesforce

I go back and forth on the level of detail I want to have in the documentation. For an automation or a profile or an object, I could get extremely detailed and list every bit of logic or field. I’ve been avoiding that because I think it would end up doubling the work of any update, and increases the chance that documentation will be out of date. Instead I’ve tried to focus on what users need to be successful (which is never every bit of detail) and what an admin would need to know to begin troubleshooting, migrating, or updating.

Salesforce Releases

Check out this Salesforce Ben writeup of the hottest Spring ’22 features. It seems to me that a lot of small to medium non-profits will care most about the Flow improvements. If you haven’t tried Flows in a while, now is a great time. They’re so much better than they were when they first launched.

NPSP Releases

If you’re a grantmaking organization and you’re not aware of the NPSP Grants Management functionality, take a look!

Scary Emails from Salesforce

If you’re getting the emails warning you about MFA, now is definitely the time to turn that on. Your users will likely find it easier than you expect! I haven’t gotten scary emails from Salesforce lately, but if you have, let me know!