4 Steps to Creating Great End User Documentation

Editor’s Note: We often get rave reviews about our Formidable Forms plugin documentation. People want to know the secret to creating great end user documentation. We thought we’d let our Formidable Forms Documentation Specialist give it to you straight from her keyboard.

Everyone enjoys writing documentation right? No? Well, if you're one of those who does not enjoy writing documentation, then this post is for you. I’m going to show you how easy it is to create great end user documentation every single time.

Why is good documentation important?

There are obviously many reasons to have good documentation, but I’ll point out a few.

• It’s helpful to your users. Documentation is often the first place users look when they have questions. If they can search the documentation and find an immediate answer to their question rather than waiting for a response, they will be more quickly satisfied.
• Not only is it helpful to the user, but it's helpful for your support team. When features are well-documented, it’s easier for the support team to find the answer to a question and quicker for them to point the user to a page rather than to spend time typing steps out.
• It’s less work for you! Good documentation can answer users' questions before they come to support, so you spend less time answering questions and troubleshooting on users' behalf.

Great end user documentation as customer service

Documentation is the best and quickest way to provide customer service. When it’s done right, documentation becomes great customer service.  If you put the time into making your documentation user friendly and full of helpful information, then it will pay off in the long run. Nothing makes users happier, more likely to return, and—most of all—more likely to refer you to other people than when they receive great customer service.

These four steps will help you create great end user documentation every time.

Step 1: Educate yourself on the product

Test, test, test!

This step is important if you don’t already know everything that the product is capable of doing. I always begin the process of documentation by picking a specific WordPress forms feature that needs documenting, then test every scenario I can think of. By doing this I’m able to sort out some of the simple things that may not need as much attention. I can also determine which items are more complex so I can give them more attention in the documentation.

Make sure to note anything that is tricky

When I am testing the product, I make sure to take note of anything that may be tricky. If it’s tricky for me, then it’s probably going to be tricky for others too. While writing out the documentation, I include notes in the steps that could be helpful. I try to be somewhat generic in the examples. Every situation is different and I do my best to include notes regarding things that could change an outcome.

Step 2: Decide what to include in the docs

How do you know what to include in the documentation? It can be overwhelming to think about documenting everything there is to know about your product. The good news is that it’s not necessary to document every single thing.

Here are some things I do before I start writing to help me decide what should be included:

Listen actively to your team and users

Before I start writing about a particular feature, I’ll ask my support team, “What questions are being asked the most by our users?” I'll also search support tickets in our help desk. Our help desk is a great resource to learn what our users are having the most issues with. If we’re getting multiple questions about a particular subject, then I know that it should be documented for the sake of our users and our support team.

Research competitors’ documentation

Besides using our help desk I also search our competitors’ documentation. I like to see what they feel is important to document and how they have documented it. This helps me determine what should be included in the docs.

Step 3: Use a good template

What is the purpose of a good documentation template?

Having a good template is crucial to creating great end user documentation. First, it allows you as the author to have a good sense of direction. Direction will keep you on task with what to write and how to write it. The last thing you want is to end up with a page that is long, boring, and overwhelming to read. A good template helps the documentation integrate with the rest of the docs that have already been written. It also just looks better when there is structure to a page. A good template will help the users get to know your structure. This will make it easier for them to locate answers.

What makes a good template?

Creating a good documentation template for Formidable Forms has come by trial and error. When we find things that work, we stick with it. Things that don’t work, we change up. It’s a work in progress and we’re still perfecting it. One thing that’s not going away, though, is the template itself. We have found that when we stick to a template, it’s much easier for our users and support team to locate answers.

Here are some things that make a good template:

Keep the template “Dummy proof”

When I write documentation, I try to make it what I call “Dummy proof.” Not that I’m calling any of you a dummy! It just means that I’m structuring and writing the documentation so that even a person with little to no experience will be able to navigate the page and understand what I’m writing about. A few ways I do this is:

• Include a table of contents
• Write out step-by-step instructions
• Use short and straightforward sentences
• Use white space and line breaks liberally to increase readability
• Break things up into different sections

Structure from least to most complex

I like to write our documentation so that it’s structured from the least to the most complex. This way the "big picture" information is at the top and easier to find.

I also do this because the items that are not as complex tend to appeal to a larger audience. The more complex it gets the more specific it usually is, which appeals to a much smaller audience. Here is an example of a template structure I use:

1. Introduction
2. Standard field options
3. Field-specific options
4. Examples—Note this is shown in a step-by-step manner so it’s easier for the user to follow.
5. Displaying the field—I like to put these in tags so the user can copy/paste without any extra formatting leftovers.
6. Developer hooks

Obviously, this structure is specific to WordPress form builder documentation, but a similar structure can apply to any technical documentation. To see this structure in a live doc, check out our Checkboxes and Radio Buttons documentation.

Step 4: Make it user-friendly and appealing

It’s all in the detail

When writing the documentation, I add a little emphasis here and there. Sometimes it’s as simple as bolding important words like “click the Submit button.” Sometimes I use quotation marks for specific words or phrases. I find it makes the instructions easier for the user to follow if key words are emphasized with bolding or quotes.

Screenshots

There are many different types of learners. This doesn’t have to make it difficult in preparing documentation though, as most can benefit from visual instruction. Having everything laid out in a textual step by step process is helpful, but adding screenshots will go further to eliminate any questions or confusion. I use a lot of screenshots in my documentation. If the screenshots are done right, you can never have too many. The thing to remember with screenshots is that they need to be replaced periodically to keep them accurate.

I use Jing to create the screenshots. Jing is great because it helps me be more precise when capturing a screenshot. It's free and it’s very user friendly.

I make sure to name all the screenshots so they are easy to locate if they need to be changed or deleted. My naming system for screenshots depends on the page that I’m working on. For example, all the screenshots in the Date field’s page begin with “date_” and is followed by a short description of the screenshot. So the first screenshot in this page is titled “date_field-calendar”.

After I have created the screenshot and adjusted it to my liking, I run it through ImageOptim to eliminate any unnecessary bulk.

GIFs

GIFs are probably one of the most intimidating things for most people just starting to create documentation. In reality, it’s not very difficult to create them. When I create a GIF, I make sure to be precise in my movements so there is no question of what I’m trying to accomplish. I move the cursor exactly where it needs to go and move it off the screen if I don’t need it any more.

I use LICEcap for my GIFs. I’ve never researched anything else, but LICEcap has worked perfect for my needs. It’s very user friendly.

Take your time when recording them. It may take only two seconds for you to perform a step. However, it’s more beneficial to turn it into a 5-6 second GIF. This way the user sees exactly what you’re doing and there’s no question or confusion.

Links to other docs

Linking to other online documentation is beneficial for the user, as well as for you the author. It helps the reader see what is possible with your product, sparks new ideas, and sometimes provides a simpler solution to the reader's question. When links are well-placed inside the online instructional text, the user won’t have to back out or open a new browser tab to search for clarification.

For the author, it eliminates duplicate copy. Instead of creating longer documentation with additional steps, insert a link to the other page. When you have documentation for one particular feature in only one place, you don’t have to worry about finding it and updating it in multiple locations.

Supporting plugins

These days there are a lot of options when it comes to WordPress plugins. Now there are even plugins that can help with managing and optimizing your knowledge base even more. A plugin like Heroic KB can help by giving your knowledge base AJAX search, adding article feedback, and providing built-in analytics. These additions could push your KB success over the top!

Conclusion

It’s tempting to let yourself off the hook by jotting a couple of things down, calling it a doc, and then jumping right back into development or support. It's more beneficial, however, to understand that documentation becomes more valuable as time goes on and as a project scales. It is as real an investment as any other in your project.

Following four key steps will help you produce great documentation each time. First, know and test your product to get you off on the right foot. Second, research what to document to ensure you include what is appropriate. Third, use a solid template to keep you on a user-friendly road map while writing. Fourth, make it presentable and appealing to ensure that what you've created will actually be palatable to the user.

I hope this has all helped! What have you found to be helpful when creating documentation? Let us know any tips or tricks you'd like to share below.