I was reading a blog article about writing documentation, and I came across this quote:
The purpose of technical documentation is to take someone who has never seen your project, teach them to be an expert user of it, and support them once they become an expert.
While that's a great definition, I think there needs to be a distinction between technical documentation and what you're trying to accomplish writing Salesforce documentation for your end users.
You are not like them
Oftentimes, Salesforce Admin and Consultants are interested in learning everything there is to know about Salesforce - it's part of your job! You want to become an expert user because it helps you excel at customizing, implementing, or rolling out Salesforce. Technical documentation is meant for you.
But most of your Salesforce users DO NOT want to become expert users - they simply want to do their job, and Salesforce happens to be part of their overall workflow. They don't want to learn everything there is to know about Campaigns, they just want to know how to set one up because that's what they were told to do. Technical documentation is NOT meant for end users.
If you are an Admin or a consultant, you have to realize that you are not like your end users. You are willing to read through lengthy technical documentation to learn everything you need to know, and extract what's important. Your end users are not willing to do that - they simply want to know the steps necessary for accomplishing a task.
How should you write documentation?
The way you write your documentation depends on who you are writing it for. If you are keeping internal notes for the Admin team or your consulting project, then you may want to write technical documentation that goes into great detail about the who, what, why, and how. Technical people tend to enjoy sitting down next to the fire, reading through the nitty gritty that is technical documentation.
If you are writing instructions for your end users, you will want to keep your articles short, visual, and fairly basic. End users typically don't read documentation, they reference it when they get stuck. For example, when Suzy (a Sales Manager or a Sales Rep) is told to create an email campaign, she doesn't want to spend a lot of time reading the technical details - she just wants to read the necessary steps for creating a campaign:
- Create the email campaign
- Define Member Status Values
- Create a target list using a report
- Execute email campaign through HubSpot
- Update responses
- Create a report to summarize responses
Obviously your instructions might be different and much more specific to your workflow, but that's a simple example of what end users want to see - pictures, arrows, a little text here and there. Suzy will appreciate everything being very straightforward and not having to read through loads of paragraphs to do a simple task.
Tips for writing technical documentation
I am not an expert on writing technical documentation. Here are some resources available that can help you become a better technical writer:
- Jacob Kaplan-Moss
- Steve Losh
- The Science of Scientific Writing
- LinkedIn Group - Technical Writing Management
- LinkedIn Group - Technical Writer
These will help you become a better technical writer, which is great if you're writing for technical people. But remember, the majority of your end users ARE NOT technical people.
5 tips for writing end user documentation
I am not an expert on writing end user documentation; however, we have come up with a great methodology for writing better end user articles.
Tip 1 - Use screenshots with annotations.
Most of the time, your end users are going to reference documentation when they want to accomplish something but can't remember how (or never had anybody show them how). Seeing an image with an arrow to the button that needs to be clicked is much easier to find, and follow, than reading through several paragraphs.
Tip 2 - Use specific tasks as titles
Articles with titles such as "Contacts" are not very helpful. But titles like, "What is a contact?" and "How to create a contact" are.
I even encourage you to get more specific than that when the situation calls for it. For example, end users don't typically have to create a general contact - they are creating customers, partners, or competitors. So write articles with titles such as:
- How to create a competitor contact
- How to create a customer contact
- How to convert a lead into a contact
- How to create a partner contact
Most of the time, end users are just executing a predefined process and are not required to make many (if any) judgement calls. So write specific articles for doing each process. They don't have to be long, they just have to show the details of what to click, the information that goes into each field, etc.
Because these are the questions your end users have - "Bob told me to create a partner contact... is that different from a customer contact? How do I create a partner contact?" If you have documentation that answers that question, your end users won't spend time thinking about it or asking you to explain the difference. Everybody will be able to quickly get answers and get back to work.
Tip 3 - Document specific workflows
End users executing a process are often being delegated a task at a level 1 - Do exactly what you have been asked to do. If you just document general guidelines and best practices about forecasting or campaigns, you are leaving room for error - several end users are not expected to make judgment calls when processes have already been established.
Instead of having documentation on how to set up campaigns, you should have documentation for:
- How to set up an email campaign,
- How to set up a direct mail campaign,
- How to set up a conference campaign, etc.
End users don't need broad instructions when they are executing specific tasks - that leads to inconsistent results. If management has already determined the process for each situation, then document the specific workflows. Plus, the more specific your workflows are, the easier they are to document
Tip 4 - Link to more in-dept information
You'll want to keep your articles free from caveats and in-depth explanations that are not related to the title of the article - these additional explanations just make things confusing.
At first, it can be difficult to accomplish this because you think, "The end user NEEDS to know this." And you might be right, they do - so just explain it in another article and then link to the explanation. This keeps articles clean and focused.
Tip 5 - Don't leave out steps
Make sure to include a description of a step, or a screenshot of each step of an onscreen process. If you leave something out, you will inevitably get a follow up question or an error in execution. It might take an extra 30 seconds, but it will save you, and your end users, a lot of time down the road.
End users are not dumb
I'll conclude by saying that end users are not dumb, we just don't have the patience to go through a lot of documentation when we want to execute a simple, onscreen task. Our thinking is that it shouldn't take 45 minutes to sift through instructions for doing a predefined task that takes 1 minutes to execute.
If an end user's job were to learn everything there is to know about Salesforce and create new workflows, then sure. But that's not our job - our job usually consists of executing operations that have already been predefined and decided for us, we just need to see the directions that show us how to do it.
