Over the past year of my internship I have created countless tutorials and application guides. I have created video tutorials walking users through complex workflows in SharePoint 2010 Foundation and simple video tutorials showing off the features of an internal team SharePoint. I have created written documentation guiding users through the data management process in Salesforce.com and all its anomalies. And, in rapid fire format, just general user information such as OCS for Blackberry, Twitter Jumpstart guide, top QR code readers for all smartphones, LED vs. LCD, desktop video conferencing options, and many more topics.
After a few initial missteps, I developed a method to all this documentation madness. I intend this post to give an inexperienced documentation creator a few tips to keep in mind when forming their user guides.
- Begin with the end in mind
- Don’t overlook the intuitive
- Picture it with pictures
- Cite your sources whenever possible
- Develop a template
Begin with the end in mind: Well, duh. But you’ll be surprised how many times I have started a Word document with a ton of research links or put 7-8 user steps together but none of it connected. Great, I now know how Facebook and Twitter can help each other but that does not tell me the steps a user must take to sign up for Twitter. (There are 5 steps, by my count.) If you have a clear and concise picture (the original name for this step), you will be able focus your documentation in a more efficient manner. Just like taking a road trip, knowing where you want to go is half the battle. You may not see as many places – sometimes that’s a good thing when it comes to the internet, it gets pretty weird out there – but you will definitely use a lot less gas and have more time for activities.
Don’t overlook the intuitive: My generation tends to take for granted the fact that user manuals are not needed for new technology and if they are present we just throw them away. I’d rather dive into a new product than to read a whole booklet teaching me how to turn it on. It’s just natural for me to figure something out as I go but many of the older business users are not like me. They don’t like exploring what this button does or where this page takes you. The point of this whole speech is to say you should document the simple stuff you might think is obvious. If you think the steps are just 1-5, take a second think if there’s a 1.a, 1.b, 1.c. Chances are the answer is, “Oh yeah…Oops.”
Picture it with pictures: Screen shots are your best friend. Your BFF Jill. Like OMG. It’s easy to say click on the settings icon above the text box but do all settings icons look the same? Are all icons created equally? Pretty sure they don’t all look the same otherwise there would be someone making mad money on the copyright infringement. Each company creates their own icons. They might have a similar look but there is always room for icon creativity. To avoid any confusion on what the icon looks like take a screen shot. Put in right next to the sentence. As simple as that.
Cite your sources whenever possible: Citing sources is extremely important in the business world and it can as simple as providing the link from where you pulled in the information. Adding your source saves you so much time and headaches. People won’t ask where you got the current number of active Facebook users from because they have the link staring them in the face. It is a beautiful thing. Make sure they are reliable sources otherwise you will be busted for providing some shoddy information. Save yourself a headache and gain some free time by providing a source for your information. The more the merrier.
Develop a template: As you begin to create more and more documentation, it is important to keep the formatting consistent. By consistent I mean a regular format you follow with bolding titles similarly, staying with the same font between papers, using the same indentation, and other formatting styles. This not only reduces the amount of work you have to do but it provides documentation with a voice and style your audience will become familiar with. It reduces your work load because the template turns all this research into a fill-in-the-blank process. “Ok, this header goes here and the source goes below it with one indent and a bullet point.” The template allows you to focus on the content you are providing versus the way it has been presented.
I hope this provides a little insight into providing documentation for business users. Remember the tips above and I think you will have a good base to start from. If you have any tips of your own, please let me know in the comments below. Thanks!