Posted by: eliz_beth | November 1, 2011

Month of Posts – #1 Tips on writing documentation

I took a little time off after Dreamforce, which turned into a lot of time off here. With November being traditionally the chance to write a novel in a month, there’s another group who is encouraging each other to write a post a day on their blog. So this month I’m going to do my best and post at least one tip, experience, or idea a day to get back into the saddle. Some may be a bit obvious, but the reason I’m posting them is because of recent situations where I’ve seen them actually occur. If you roll your eyes, take it as a reminder to use when you review your next activity.

Today’s tip is regarding creating documentation for your users. It doesn’t matter how many times you show a user how to do something or how simple you make the process, at some point you will either need or want to document the process. If you are not set up with something slick to basically make videos of your clicks and commentary on a screen, you’re definitely going to go with the traditional written format.

An important component of documentation is taking screenshots of the related materials. There are many tools available to assist you such as SnagIt, but sometimes you have to work with what you have and that is Microsoft Paint. A little alt-print screen, some paste into Paint, and wha-la you have the basis for your screenshot. You can use various tools in Paint to crop, resize, emphasize, and obscure the picture to fit your needs.

Here’s some helpful hints when taking and working on your screenshots:

1- If you can, create screenshots using dummy data, preferably from a sandbox instance that is a recent full copy of your instance. If not, production is acceptable but watch for the following:
A- If using production data, make sure the information being shared is not details that should remain private to all possible viewers of the document
B- Create a dummy account/records to use to take screenshots of to protect your regular data. Be sure to clean them up after the project, or make sure the data associated is not included in reports, etc.
C- If you can’t go the dummy route or the sandbox route, unless you absolultely need to show figures, use Paint or the tool of choice to obscure sensitive data. Erase it, cover it, blur it- whatever works best for you.

2- When taking the screenshots, make sure you are logged in and displaying the screens as the audience you are writing for. Sometimes you may have to make this a generic choice, but if you can accommodate your screenshots to match what the user is going to see, your work will look much more professional and will go a long ways to prevent misunderstandings. Users will believe what they see on the page- if that is different than what they see on the screen, their confidence levels will be dropped and the rate they ask questions.

3- Provide clear definitions and processes. While most documents do not need to be extremely detailed it does need to be clear. In the past I’ve often created two versions of the same document– a fully detailed version with complete descriptions, step by step instructions, and included what the typical errors may include, and a second versions which was a quicker summary with just the main steps involved. The quick references were used after initial learning took place, the full document was used for learning and reference.

4- Consistency of terminology. If something has multiple acceptable names, that is fine- explain that. Don’t use them interchangeably without verifying for the user they are the same and it is acceptable practice.

5- Note on your document:
A- What it is about – typically covered in the title
B- Who is it for?
C- What version of the document
D- What version of the associated software was it written for
E- Author(s) of the document.

So those are a few tips to keep in mind when creating documentation for your Salesforce users. I hope you’ll continue reading this month and if you have any particular areas you’d like to see covered, leave a comment!


  1. Great post. These are great tips for the creation of documentation. My single biggest issue is getting users to read the documentation vs. picking up the phone and calling me. A post on leading users to water to drink would be great.

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 )

Facebook photo

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

Connecting to %s


%d bloggers like this: