Why Your Salesforce Documentation Needs a Table of Contents

Posted by Jonathan DeVore

actual-menuSome online knowledge base software (e.g. wikis) assume end-users know the questions they want to ask, so the software is optimized for search. The problem is, this approach leaves out end-users who don't know what question to search with, or what the options are.

Using an index

I was reading a blog post by Seth Godin about menus vs. indexes. The article wasn't about customer support (he blogs about marketing and entrepreneurship), but it got me thinking about how online self-support could be improved.

Seth asserted that "Google killed the old-fashioned cookbook" because most folks don't flip through a thick cookbook anymore - they just type in a few keywords and hit "search." 

Well, the same is true for self-support knowledge bases. End users don't flip through a PDF, Word document, or a hundred wiki articles when they want to find an answer - they simply enter their question into a search field and hit "search."


A searchable help index allows end users to find whatever they want with very little trouble, and in hardly any time. But there are some limitations to relying only on the power of search.

Give end users a menu

In the same article, Mr. Godin brings to light a problem with the index and relying only on search - If people are left to just search an index, they search for what they know and are what they are comfortable with, leaving them unaware of other possibilities. (They may not search at all if they can't articluate their questions.)

For example, if you were at a restaurant and the waiter said, "What do you want to eat?" What would you order? If you don't have a menu of items to choose from, you would probably order what you're famililar with. If you were at a new restaurant, you wouldn't know what to order because you don't know what's possible.


A menu communicates what is possible, and reveals options that might have never crossed anybody's mind. The image above is an example of the online table of contents for working in our ScreenSteps application. If somebody is scanning through our online knowledge base, they can see a menu of options for working with manuals and articles - very helpful for our customers who aren't aware of what's possible.

We have to offer a menu, we have to curate choices, we have to dream for people who don't have the guts or time to dream for themselves.

Seth Godin

Sometimes during a demo of ScreenSteps, folks don't care about the structure of articles - they just want to create better help articles using screenshots and stick them into their wiki or some other online service. But not having a structure hurts the usefulness of documentation.

In Salesforce, you will have end users who need a menu of options because they don't know what they can actually do in Salesforce. To show some of the possibilities, have a table of contents that is descriptive and easy to scan. If you're creating a PDF/Word document, then you already know this. Just make sure your online knowledge base has this ability.

End users need an index and a menu

Make your Salesforce documentation flexible so your end users can quickly get answers via search, and quickly scan a menu of possibilities via table of contents.

Just like a restaurant organizes its food menu (e.g. lunch, dinner; chicken, pasta), organize your table of contents so that it groups similar content together (e.g. Leads, Opportunities; connecting with contacts, following up). The easier it is for your end users to see what's possible, the more likely they are to take advantage of all of its features.

Free eBook: The Pragmatic Guide to Training and Onboarding Salesforce Users in Your Nonprofit

Image provided by creative commons: FLIKR - http://flic.kr/p/5a7pvt



Topics: Salesforce documentation tips