Thoughts on technology and innovation
Ted Husted, Release Engineer
How you can implement a custom help site for your Salesforce org, like the one at help.nimbleams.com (in three parts).
Warning: There's a lot you can do to extend Salesforce help, but we need to create a few prerequisites along the way. Part 1 of this blog (you are here) steps through the org setup. Part 2 covers the setup for an external online help site. For extra credit, part 3 walks through creating and maintaining a help site using the DITA XML format.
Salesforce Help Options
What are your alternatives for customizing Salesforce help?
One of the marvels of working with Salesforce is the seamless way customizations blend together on the Force.com platform. From the user's perspective, custom capabilities and standard capabilities all look-and-feel alike.
One exception can be "Help for this Page" (HFTP). Much of the Force.com UI is composed of tab controls that are collected into "apps". Users can switch between apps to quickly access different sets of tabs. Each tab can provide its own documentation via "Help for this Page" link at the top-right corner of each tab.
On standard tabs, HFTP bounces over to a relevant topic on help.salesforce.com -- now part of the truly useful Salesforce Success Community. For custom tabs, HFTP defaults to a generic "Defining Custom Objects" topic.
A tab is associated with an object, and each custom object has a "Context-Sensitive Help Setting" with three options, including the default behavior.
Custom s-controls are deprecated. Moving forward, your only real custom option is a Visualforce page. In turn, there are a couple of ways you can leverage the Visualforce page.
Using either Visualforce straight-up or using a shared document are fair options if you only need to provide a single Help page for each tab. For many apps, certainly, one page can be sufficient. Other apps justify more extensive documentation.
For more background, see Getting Started with Object-Level Help.
If you you have extensive documentation, and want to maintain it all in one place, the better approach can be to use the Visualforce page to redirect to an external help site. Let's have a look.
Before you can configure your org to use a custom help site, there are three prerequisites to create (plus having the help site).
Custom Help Setting
Create a custom setting to point to your help site. By using a custom setting, we can avoid hard-coding the name of an external site into code that can be cumbersome to change.
HelpRedirect Apex Class
Create an Visualforce page controller, to route to your help site. Note that I'm choosing to redirect to an URL like "help.nimbleams.com/Affiliations", but you can use whatever URL works for you. Just have your PageReference methods return something different. We also keep all the literal reference to the help site in this one class. If the help site is ever revamped, this class is the only component that needs to change.
HelpRedirect Visualforce Page Template.
Create a HelpRedirect Visualforce page for each object to call the corresponding method on the controller. We chose to keep the Visualforce pages simple and defer the logic to the controller. All the page does here is call a method on controller, and the controller does the rest.
Adding Help For This Page to a Custom Tab
Link a custom tab to an online help via a custom Visualforce page.
How often do you use Salesforce Help for this Page? Should more managed applications provide integrated help? Or does linking to a PDF work just as well?
Ted Husted is a release engineer for Nimble AMS. "It's my job to make sure that we ship everything that's done, but not before its ready."