Effective Documentation: The Friendly "Transformative Guide"

While researching on how to improve user documentation, I came across an inspirational guide on creating passionate software users titled Attenuation and the suck threshold. It’s quite an interesting take on improving the user experience. Based on the ideas in the article, I was inspired to write about how we can improve user documentation to make up for a less-than-intuitive complex application.

From first impressions to higher ego

Understanding the human psychology in relation to using software helps in designing better and more intuitive software. However, no matter how intuitive the software is, you can always observe that there are several phases a user goes through while using the software.


First impressions

The first phase is the “First impressions” phase. This is an important phase when the user decides to use the software or not.

You can either make the interface intuitive or attractive. An intuitive interface makes the software less intimidating and friendly. A less intuitive but attractive interface does not make the software any friendlier but the user does become “friendlier” to the software; not unlike the attractions of a sleek sports car – no matter how hard it is to drive one. At the very least, if you can’t make the software interface intuitive or attractive, you can always give the software a good first impression with an interesting “What I can do” list – either during installation or at first startup.

This sucks!

The second phase is the “How can I get this done?” phase, or more likely known as “This software sucks!” phase. This is when frustrations build as the user tries to learn the software in order to accomplish the user’s original goal.

The length of this phase may be a fraction of a second, a few minutes, or an hour or two. It rarely goes beyond that. After an hour or two and still failing to accomplish the user’s goal, the “How do I close this?” phase kicks in. Sometimes, when a user just had to use the software because that’s what the IT department prescribed, the user would use it grudgingly and all the time stays stuck in the “I hate this crap!” mode.

Feeding the ego

The trick to a good user experience is to move them from “This software sucks!” phase into the “Yeah, I rule!” phase by giving the user a sense of success. If not a complete accomplishment of what the user wants to perform, at least by having the user complete the first step of the complete process.

As a rule of thumb, just ask yourself this question: If I open a word-processor application to type a letter, and I have to spend the first hour finding out how to create a blank document, how would I feel? Well, that’s almost impossible nowadays but veterans can still remember the first time they started WordPerfect for DOS.

However, even if you still don’t know how to create a letterhead for the letter in the first hour, being able to type “Dear sir,” is an accomplishment that keeps you trying to learn the more complex features of the software.

That on-top-of-the-world feeling

Remember the first time you get to insert a picture in the letter, resize it, and place it exactly where you want? Felt like you rule the world, didn’t you? Especially for those MS-DOS veterans trying to insert graphics in WordStar where you can’t do that easily unless you have Hijaak. Remember the feeling?

Now, that is a software moment.

Creating success through documentation

So what does this have to do with documentation? If the software is intuitive enough to bring the user from the “This software sucks!” phase into the “Yeah, I rule!” phase by itself, the role of documentation is only to complement the software.

For example, the user finds it intuitive enough to create a purchase order in an ERP application and does not need the documentation to complete the task. However, the user might have questions as what will happen exactly when the user clicks “Save”. Will the purchase order be printed? Will it be automatically sent to the supplier? Where can I find it back for later? This is where the documentation comes in. Apart from clarifying to the user all the fields available, the documentation should also help clarify what will happen and how to move forward.

However, there are times when the software by itself can never move the user from the negative first phase to the positive second phase. And you just can’t change your software interface due to the complexity of the software or you need to cater to a different audience. For example, although you could have created “wizards” to guide the user in creating an asset item in the ERP application, it will make things slower or there are just too many ways to complete a business process that a “wizard” is just too distracting even for beginners. For example, how long will the “wizard” be, since the user must first create the account, then create the item, and then link the item as an asset?

Seems simple but consider this: How many times during the process that the user needs to put the “wizard” on pause mode to create other accounts to complement the asset account? How many times the user has to call the logistics department to ask about item policies? How long will it take for the user to go to the corporate accounting department to get clearance for the asset creation? Add this one more question: Can all these be done by one user in one sitting?

As you can see, in this situation, the “wizard” will move the user from the “This software sucks!” phase into “I hate this crap!” mode faster than not having the “wizard”.

In this situation, the only way to make up for the complexity is through documentation. Or more specifically what I call a “transformative guide”. The guide must be able to transform the user from a sulking novice to a novice-with-grand-ego (the novice who can say “Yeah, I rule!”).

The transformative guide

A “transformative guide” helps the user to perform a particular task in the easiest and fastest way possible. As you can see from the previous example of creating the asset item, it is not straight forward. Even a simple step-by-step instruction won’t cut it.

You can’t write a whole book on how to set up accounts! But what you can do is recognize that there are experts in certain areas and that the application is only a tool. The experts are still needed to perform the tasks using the application.

So in this instance, a “transformative guide” informs the current user what are the basic requirements and where to get help. For example, you can just tell the user that an asset account is needed and link to another transformative guide that is written specifically for accountants. The user then goes to the company accountant and asks the accountant to create the asset account and the complementary accounts, or whatever else needed.

The guide itself must assume that the accountant knows what he or she is doing and just guide on what to prepare (such as the account numbers, the type of accounts, and those kind of things) and which part of the software can be used to create such things. Do not bother to explain what an asset account is – it’s just intuitive to the accountant. We are not trying to replace the role of accountants – we are just providing the tools and guide the accountants on how to use the tools.

Part one: Tailor it to a suitable audience and be clear about it

In other words, do not overstep the boundary and do not assume that there is only one audience. Each document must assume a particular type of audience and announce at the beginning the audience that is expected. This should clear up on a lot of things and reduces frustration. If you are not an accountant, you won’t feel frustrated reading a guide about creating an account if it’s specified at the top that the guide is meant for accountants.

What we are not saying, by specifying the target audience, is that “If you expect to create an account in our application while not having enough accounting knowledge, we can help you to create the account but we can’t guarantee that your balance sheet will be accurate”. In simple words, “This part of the software is not for you”.

This will be the first taste of success for the user – knowing that he or she is the correct person to perform the task.

Part two: Specify the pre-requisites and point to other relevant guides

The next part of the “transformative guide” is to specify the pre-requisites. List all that need to be done before doing a particular task and inform the user the type of the pre-requisite task and where the user can find the relevant documents.

Better still, specify the knowledge required. For example, if an asset account is required before creating an asset item, inform the user on the fact and tell the user that accounting knowledge is required. Then, point the user to the right direction to fulfill the prerequisites. If there are relevant “transformative guides”, provide a link or tell the user where to get them. Since a “transformative guide” specifies the target audience, the user will soon find out what pre-requisite knowledge is required to perform the pre-requisite steps.

Which bring us to the point: pre-requisites also include knowledge. Even though the document already specifies the target audience, do not assume that if a user fits the target audience criteria, the user have the required knowledge. For example, we might state that the target audience is the assets manager and as it happens, the user is the company’s assets manager. But does the assets manager knows about the company’s policy on standard item coding used for the company? Maybe the manager does, or maybe not.

Of course we are not going to explain the whole thing but at least we can specify what are the information and knowledge that must be prepared before performing the task. This can greatly help the manager to go and refer to other relevant people in the company. Remember, although the software captures as much as possible of the business processes, it can never capture all aspects.

The user will taste the second success here – prepared to accomplish his or her goal.

Part three: Guide the hands that shape the world

Once the user is prepared with all the pre-requisites; the account number and type, the item code, the asset code, and things like that; guide the user on the steps to accomplish the task.

As a rule of thumb, keep it simple and straight to the point. Do not bother to explain in details about the particulars in each step. Remember, we have already set an assumption of who the user is and what the user knows. Also don’t bother to list all intricacies such as what else need to be there beforehand as that has already been explained in the pre-requisites.

Instead, the step-by-step part of a “transformative guide” should be focusing on the hands-on aspect as well as explaining the effect of each action. However, it is better not to explain that clicking something will enable something else as it will only distract the user on the various possibilities. Remember, it doesn’t matter if an action enables something else as what matters is what needs to be done to enable something we want to use at the moment. In other words, tell them to enter the account code and what is the effect on the item, i.e. the item is now linked to the account.

In keeping it simple, it is better to explain the shortest route possible to complete just the necessary steps so that the user can click “Save” or “Create”. Make the journey to success as short as possible. We can explain all the intricacies later. For example, the user can set up quite a lot of things for the asset item such as a photograph of the asset, link an owner to the asset, and set up the depreciation method. Don’t bother explaining those yet.

Focus on one goal and explain how to reach that goal. If the guide is on creating an asset item, focus on the “creating” part. All other parts can be in another document that you can call something like “Advance assets item customization”. It doesn’t have to be something really advanced but the word “advanced” there should help with the ego.

Once the steps have been completed, the user should already accomplish his or her goal that is to create an asset item in the application. And if it’s done in a fairly short time and with minimal problems, this is when the user can claim “Yeah, I rule!” Well, sort of.

Part four: Sweet success made sweeter

Remember the final rule: congratulate the user. Of course, you don’t have to say “Congratulations!” That’s too obvious and cheesy. Think of another way like “Now you have created an asset item entry. This entry can later be used by your colleagues and you to monitor and service the asset.”

Yes, put the user on top of the world.

Part five: The aftermath of success

After the user has completed the goal, the work does not stop there. Provide some simple suggestions on how the user can proceed to capitalize on their first completed goal. For example, creating an asset item is simply the first step. The next step will be to customize the asset item with a photograph, link an asset owner, and more advanced things like setting up the depreciation.

Although the user should already know all of that, it doesn’t hurt to suggest. You can ask the user what he or she wants to do next and list the possibilities. This is where you can link to other “transformative guides” so the success doesn’t stop here. Goad the user to more successes in using the application.

The important thing to remember here is that you can’t guide the user all the way. You can show the user how to start. Once the user is familiar with the application, he or she can explore – whether by reading more documents or by just trying out the application.


The “transformative guide” does not just provide the user with steps to complete the task but also whether the user is suitable to do the task. It also guides the user on the preparations before actually performing the software task. And once the task is completed – it should be as easy as possible since all the hard part is done in preparation – guide the user on where to go next.

In other words, it’s not just a step by step guide. Instead, it transforms the user from a novice who is intimidated by the complex software to a novice who now believes he or she rules the software. Of course, they are still novices but now with the determination to keep on using the software and with enough basics to explore without fear.

That is the goal – to transform the user from a fearful user to a confident user, novice or not.

By the way, try to be friendly but don’t overdo it. It may not be commonplace in software documentation but a bit of humor helps reduce any anxiety a new user feels. I mean, would you have bothered to read up to here if this is an “academic” article using all sorts of academic jargons?

Information and Links

Join the fray by commenting, tracking what others have to say, or linking to it from your blog.

Other Posts

Bad Behavior has blocked 49 access attempts in the last 7 days.