You must document your Salesforce org, but do it right

Like most people, I always need to fight off the feeling of being overwhelmed when presented with a Salesforce environment that’s been active for many years. The core architecture  is almost always sound, it’s the edge cases that the system supports which worry me.

I’m currently trying to de-bug why I can’t de-activate a user because the user is referenced in an opportunity workflow field update. Of course none of the documentation makes reference, or aludes to the idea that a user is referenced in a field update. This forces me to go through every rule to locate the dependancy … fun.

The problem with documentation.
Documentation is a chore, and we all know that no one likes to read documentation – it’s only referenced anyway. To make it even more complicated, one of the chief benefits of Salesforce is the speed that we can implement changes. All it takes is a simple modification of a workflow rule, and your documentation is out of date.

Inline documentation
We can take a lesson from newer development tools and practices where documentation is written inline with the application code. Salesforce provides us a name, and more importantly a description filed for all fields, workflow rules, templates, etc. It’s in the description filed that you need to document the following.

• The behaviour of the feature. This is the reason why the feature exists, and is the most important thing to document.
• The dependancies. If the rule only fires because of some other action, document that action.
• How the feature works. If you still have the time and patience, document how the feature works. But remember, often all the user needs to do is view the formula to see this information.

Even when we document, we often do it wrong!
We generally document backwards. We tend to document technical attributes of a feature, but not the reason the feature is there. For example, it’s typical to see “this workflow rule sends an email to the account owner”. However, this statement is irrelevant because all I need to do is look at the rule to figure this out. What I need know when I take over your Salesforce account, is why you’re emailing the account manager, not the fact that you are. Your documentation doesn’t tell me that the update is designed to tell the account manager that implementation services are required.

This kind of documentation let’s me quickly respond when someone asks “can we add the CSM team to the notification email, when implementation services are required”. Business people talk in use cases, your documentation should too.