Last week in Documentation Done Cheap I suggested that you probably have access to a free way to house a Salesforce documentation wiki. Let’s talk a little about what to put there.
1: Just Start Writing
I mean it! Don’t let the perfect be the enemy of the good. (Don’t even let the good be the enemy of the somewhat-adequate.)
Any documentation whatsoever, even full of sentence fragments, bulleted lists, and typos is better than nothing.
Even before you can start building specifics, you want to have some kind of guide for your users to understand what Salesforce is, why you’re using it, what assumptions are baked into your implementation, etc. You can polish later. But if you don’t get the basic foundation constructed early you’ll always be playing catch-up.
2: Basics: A Welcoming, Fun Roadmap
Make the front page welcoming and make things fun! I like to adopt a fairly informal tone. It puts users at ease and helps them understand that this is a living document that needs their help to keep it up to date.
If you can, put in pretty pictures. I like LucidChart to easily build a diagram of the relationships between database objects. I’m no graphic designer, but I think this is pretty good looking:
Perhaps throw in some links to Salesforce’s documentation of the features you’re using. You can see, in this screenshot, that I literally start with a link to the NPSP documentation. Not that I expect too many users to follow that link. (Who are we kidding?) But I want to set the expectation that whenever possible I’m going to let Salesforce.org handle the documentation of their own features.
(Pro Tip: Have you seen the amazing videos produced by the volunteer NPSP Videography Team? Whenever possible, include links to those videos to introduce your users to functionality from Salesforce.org’s products.)
3: A Page for Every Object
Next I create a page for every commonly-used object.
At first some of them (particularly the Salesforce standard objects) might seem kinda’ stupid.
That’s fine. That might even be all there is to say at first. But pretty soon, you’re going to find ways to expand on this with commentary that is specific to your organization and your Salesforce instance. Better to give yourself the placeholder page right now. Eventually you’ll have time to expand to specifics:
But far more important than those standard objects is to start recording your org’s custom objects. Hopefully a lot of them are just as obvious as Contacts, based on the object name and understanding your organization’s programming. But this is the place to call out all the assumptions on which your instance has been architected.
For example, let’s say you have an object named Program Enrollment that is a child object to Contact and also child to Program. Most of us reading this blog probably understand that Programs should have records for every program offering of your organization. And having a Program Enrollment is the only way to know which contacts are part of those programs. And it, therefore, follows that only contacts for whom there is one or more enrollment record are “participants” in our program.
Now is the time to write that out explicitly! If you have an enrollment, you’re a participant. If you don’t have an enrollment, you’re not a participant. It’s that simple. When someone comes looking for a report of “how many participants have we had this year?” it’s going to be much easier to answer that question for them if they understand in advance that “participant” is defined as “a contact that has a program enrollment.” Now they probably already know what reporting they need!
So give yourself a page for each of your custom objects and, even if it seems obvious, be explicit about why they represent and how they are used.
4: Make a Web of Links
Strictly speaking, I’m going to say this step is optional. But one of the main reasons I suggested in last week’s article that you should build a wiki is that you’re going to have an easy way to link your pages together. One page per object, like I suggested above, is easy to maintain and keeps pages short (so lazy people will read them).
Certain objects get used together. So make it your practice to give internal links. Whenever you mention an object, make that mention a link to that object’s page. And when you add a new page for a new object, try to remember and go back to previously-created pages and add links to this new page.
If your site builder allows for a hierarchical menu, take advantage of it. But if not, at least one page for each object is pretty easy to browse through.
It sounds obvious, but it’s very helpful to your readers.
5: Clear Descriptions of Automation
Automation is fantastic! Users love how it makes their lives easier. Automation is part of why I say that Salesforce can be custom software to run your nonprofit.
But automation can also be pretty opaque. You might see part of what happens when automation runs, but other things that happen could be hidden, or at least not obvious. So give your users a way to understand what happens when they do something and why.
It might make sense to devote a page of your wiki to describing automation. Or it might be better to integrate the automation documentation into the page(s) of the objects in question. But just get something written down so your users (and other admins, and even Future You) have some bread crumbs they can follow.
List it all out:
When the Enrollment Status field is changed to Withdrawn there is automation that creates a Task assigned to Reggie. This task is Reggie’s reminder that the student’s email account should be closed and the status of any outstanding tuition balances evaluated.
As simple and understandable as that paragraph is, let’s point out that it does quite a few things:
For users, it lets them know that changing the enrollment status field is the action that actually un-enrolls a student. (This should probably also be explicit on any pages about students, or programs, or contacts.)
For Reggie, it’s documentation of how these tasks keep getting assigned to him.
For the organization, it documents the things that need to happen when a student withdraws.
For Salesforce admins, it documents that Reggie is explicitly built into the automation. If Reggie leaves, you are going to need to change the automation to point to his successor.
That’s a lot in just two sentences!
One final word: On pages focused more on the user than the system admin you might not use all the jargon about how the automation works. I wrote “there is automation” above. But if you're working on pages for sysadmins, you might want to say “there is a flow...”
6: A Page About Installed Packages
Most orgs have several AppExchange packages installed in their system. Sysadmins will know how to go into Setup and see the complete list. But any apps that users will interact with may be worth explaining a little bit on the wiki (and linking to their creator's own documentation.) This is also a good place to give future sysadmins a little leg up in figuring out when and why you have installed one package or another.
I could go on and on, but that’s really plenty to get you going, I think. There’s just one last thing: getting your colleagues to read your wiki. I’m not gonna’ lie: people are lazy. Most of the time they’re either going to ask you directly for help or their going to just not do the thing they can’t remember how to do. I can’t beat human nature. But I can make it easier for you to answer their questions!
Be Relentless:
Every single time you answer a Salesforce question, do so by giving a link to the page on the wiki that they can reference in the future. (If you have to, write that page quickly and then link to it as though it was always there! I won't tell.)
Relentlessly mention and link to “the wiki. The wiki. The wiki.” It takes time, but people will start to realize that when they ask you a question they’re likely to get a link to the wiki. Eventually, they'll even look at it for themselves.
Make It Easy to Find:
It’s one thing to link to the wiki in emails and Chatter posts. But if you really want your users to start going there on their own, you have to make it easy for them to find.
Put a link front and center on the homepage so they see it every time they log in. In Lightning you can even customize the help menu (question mark) so a link to the wiki is available no matter where people are in Salesforce:
And every time you do any sort of training, point out to people that a link to the wiki is there in the help menu.
Once your users catch on, you might even find that your “Salesforce wiki” morphs into your “Organization Handbook.” How great is that?
Commentaires