Making the Case for Documentation

It seems appropriate that my first post on this new blog would be about documentation. How meta! When I say documentation here, I’m focusing on documenting what’s happening in the setup menu for the benefit of anyone searching or trying to make sense of administrative settings, though much of this applies to different kinds of documentation.

I have thought about this topic so many times since starting at my most recent job as a Salesforce Administrator at Year Up, a large nonprofit organization with 600 (and counting) active Salesforce users and a dedicated team of 7 working on current and future Salesforce functionality. Why is documentation so important in a Salesforce setup environment?

Perhaps the most obvious: no one knows exactly what you’re doing or why, except you

None of us works in a bubble, even when we are a rockstar solo admin. If we rock enough, we’ll head off to a bigger, brighter organization after some time. And someone’s going to have to know why you did what you did.

Sometimes even you don’t know why you did something

Right in the moment you think, this makes total sense! And I need to do this task and move on so I can get on with my busy day. And some time later, you stumble on that same formula field and cannot remember why you put it there. This morning my co-admin asked me why I created a particular Public Group six months ago. Now, I remembered creating the group, and I remembered that there was an actual reason for it. I went digging through the helpdesk ticket archive, sharing rules, report folders. Nothing. Oops. Could have prevented this one, easily, with some simple documentation.

Nonprofit Salesforce setup can be complex

When you’re building custom fields, workflows, validation rules, and processes that are specific to your organization’s mission, program, and business processes, things that start off seeming fairly obvious can get obscure pretty quickly once you’ve gathered your requirements from your staff and started building. Furthermore, if you’re paying a developer write a trigger for you, or you’re an #AwesomeDeveloper and are writing it yourself like a rockstar, I can tell you for certain that no one knows what that thing does besides you. And I’m sure it does a lot of cool stuff, because it’s custom coded.

Data is flying in from everywhere!

Where did this data come from? Was a big mantra at my last system administrator job. We had data generating and updating from webforms, a gift processing vendor, custom apex code, and the Rollup Helper application, not to mention from our own users. If you have a field only being updated by one of those groups, put it in the field description! We incorporated this as standard procedure for adding new rollups. The description would read something like:

Populated by rollup helper {insert link to rollup details here}.

Simple as that. That way, when you, a fellow administrator, your successor, or anyone else with admin access goes into the setup menu to understand what the field means, they can find out easily and quickly.

So why is it worth our time, and therefore our money, to do this?

The short answer to this one is that a little bit of time invested at the beginning can save hours of time later on. Not prioritizing documentation is taking a short-sighted view of Salesforce implementation and maintenance. Helping yourself – or your coworker or successor – remember or understand what you did can prevent the frustration and time of digging through the setup menu for an afternoon, running 5 reports, calling vendor helpdesks, deleting something important (because no one understands its importance), or reinventing the wheel by putting something in the system that might already be there with a different name but no description.

But I’m using a consultant, and they’re doing all of our buildout for us!

The case for documentation might be even stronger if you’re working with an implementation partner. They’re building stuff for you – make sure they give you some documentation for what they did, and why! It will likely save you hours of time and headaches later. Remember, Salesforce implementation is an ongoing process, not a one-shot deal. The more your consultant documents, the less likely it is that you’ll have to call them again and again to ask questions or modify something after the solution has been implemented.

Where should I put it?

Anywhere where it will be easy to find, search, and update. Use description fields everywhere you go and make it a standard part of adding any new field, workflow, validation rule, etc. If we’re talking lots of complexity, like a custom object, use Salesforce Solutions! Start a wiki! Use your organization’s intranet, if you like it and it meets the criteria above (easy to find, search, and update). Start a Word doc or a google doc!

Last tip: documenting does not have to be wordy or complex. Outline the basics of whatever you built. Your reader will thank you for your brevity – because it will make their job easier. And with that, happy documenting!


12 thoughts on “Making the Case for Documentation

  1. Enjoyed the post, I’d add that sometimes there is divergence in what business users are expecting when they hear you have documentation so its important to define the types of documentation.

    There is User Guide documentation – great for end users but time intensive and brittle. There is Admin/Developer documentation (which you’re going for, it sounds like) – less brittle, more “holistic” summary of business logic, business objects and how they interact. I find this level has been the best return on investment for us to date.

    Then we have release mgmt documentation made by our developers, which is not a narrative document or guide but more a change log….easy to produce and impactful at a point in time but ultimately not what people are going to use often.

    Then there’s classic “business logic-to-code documentation” I hear people ask for, often non-technical managers who use offshore developers (this trigger does X, utility class does Y): which I find answers probably the wrong question. In place of code documentation you can substitute the standard ‘ApexDoc’ type documentation, and if you code using design patterns (Domain Layer, Service layer) they begin document themselves for any devs interested in pulling apart codebase.

    What’s the most important documentation to do? The kind you can keep up with 🙂


  2. Hi Vered. Congratulations for your first post 🙂 I like the idea about Salesforce solutions. It is pity Salesforce doesn’t donate Salesforce Knowledge license as part of donation program, it would be really helpful…..

    Liked by 1 person

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s