A User Guide is similar to any other document. Yet, it has its own prominence because it acts as a Bible for the tool, application, or software that we use. The technical writer should hence be very careful while preparing a User Guide. There are numerous resources on the Internet that explain the process of making a User Guide - audience analysis, document planning, implementation, review and delivery. Yet, there are certain nuances of a User Guide that a technical writer should understand and apply effectively.
Why?
This is the first question that appears before executing any task. Some perceived personal benefit has to be there before beginning some task. When the user changes from a very old system to a completely new system, the user guide should begin with specifying a solid reason to upgrade to the new system. Either the new system saves time or money. These are the basic motivators for any reader to go ahead. Yet, there are many other motivators that the technical writer can include in the first few sentences of the introduction to grab the attention of the reader. The user, after perceiving a tangible benefit, will be interested to go ahead and try using the application. The tangibility factor is very significant because users might not actually prefer to use any tool that can make them happy without actually knowing how it brings about satisfaction or happiness. It should either help the user save time, or work efficiently or enhance the quality of work.
What?
Once the user is aware of benefits of using the tool, the education about what the tool actually is begins. If it is a software application, the user should clearly understand the purpose of each function in the software before trying to use the functionality. Likewise, it is obviously important for the user to know the process of the flow of application as a whole. Remember to interconnect the different parts of the tool in this section. The user should be able to relate it to other parts with ease. Users are classified as experts, technicians, specialists, and non-specialists. Since it is the responsibility of the technical writer to cater to all of them, care should be taken to phrase the 'what' part of the user guide to explain it clearly to the intended audience. If the audience includes only experts, the writer is fortunate enough to write this part using the appropriate technical jargon. As the process of finding the exact audience becomes hard, the composition of this part also becomes hard. Hence, the technical writer should avoid any complications and pen down thoughts and experiences in a simple and clear fashion.
How?
Now that you have explained the user what the tool is about, you can go about telling how to use it. There are different style guides available that advocate different ways to do it. Yet, the most popular way remains to break this process into a series of steps so that the user does not get confused while trying the tool. Break down the process into smaller chunks and then you can easily write the process in a series of steps. The technical writer should come up with a good number of topics by getting into the shoes of the user and then write step by step instructions for each topic and its sub-topics. The other important point is that there would always be more than one way to do a particular task. The writer should take adequate care and document all the possible ways so that the user is not confused after treading a new path.
Additional open-ended questions such as who, where, when, and what also provide answers that fill in the required answers for your guide. Ultimately the most important thing that the technical writer has to bear in mind is that the user guide should not display the talent of the writer and the writer’s expertise in playing with words. It should instead be empathetic to the user and clearly answer any questions that might arise in the mind of the user, who actually works with the system.
While the TOC, index, and copyrights page include the essential elements of a user guide, the information should be classified into the following - definition, procedure, and a reference. Structured authoring plays a significant role in determining these elements and it also helps in making the process of information gathering easy.
