In the technical writing world, before we start to write anything, we are trained to ask ourselves two questions about the expected content: Who is the audience? and What is the purpose? The answers to these questions determine the structure of our sentences, beginning with our first written word and ending with our last.
In an example of writing installation guides, the answers to the questions are often the same: the audience is the customer and the purpose is to provide instructions on how to install the product. Beginning technical writers might take those answers as fact and hustle to start documenting the process beginning with step 1.
However, at Epicor University, we take those stock answers not as the definitive replies but as a good starting point for diving in deeper to get to the real answers. And to do that, we need to ask one more question: What is the audience’s perspective?
It’s true that usually the audience is the customer. But we need to know more than that; we need to understand the customer’s point of view. Each customer reads an installation guide from a specific point of view and certain expectations are attached to each view. In order for a technical writer to meet – and exceed – those expectations, the writer must consider as many perspectives as possible.
For example, is this a new customer installing our product for the first time? If yes, then in addition to precisely written steps, we must also include conceptual information to assist in making pre-installation decisions. Some of these decisions are determined only the first time the product is installed and the answers set the stage for the whole implementation, so it is important that we provide all the information necessary for customers to make the right decisions.
On the other hand, is this an existing customer who has installed our product so many times that he could do it with his eyes closed? If yes, then don’t add any new important, yet subtle, steps in the Getting Started section. Most likely this experienced customer is going to start reading the install guide where it says “Install the Product” even if that section starts on page 33 of an 80 page document. Knowing the perspective helps a technical writer remember that it is not up to the customer to find subtle additions; it is the technical writer’s responsibility to make sure the information goes where the customer will find it.
Sure, in a perfect world, a reader of an installation guide would start at the title page, and then flip to the disclaimer page to review the latest legal statement, and then spend a few minutes perusing the Table of Contents. After becoming acquainted with the structure of the guide, the reader would begin on section 1, step 1, which is usually the Getting Started or Pre-Installation section.
Recently I’ve had the opportunity to discuss the Epicor documentation with some of our customers; real customers working in the real world. I’ve also been reminded that our customers do not live in the perfect world that is described above. Some of their honest comments made me cringe while others made me blush. With either reaction, I’ve never doubted that Epicor customers are busy, highly intelligent, and professional people. Installing or upgrading their software is just one of many tasks they will undertake in a normal day. Many will tackle the install guide like they do any of their other tasks, which is to get their job done as efficiently and effectively as possible.
In Epicor University, we strive to keep the audience, purpose, and most importantly, the audience’s perspective in our heads with every word we write. It helps us to write the most succinct steps, the type of steps that leave no gray area, include no vague phrases, and leave no questions unanswered.
For me personally, I’m going to remember that the Getting Started section is not a prologue to a great novel; it’s not everyone’s starting point and even in a novel, some people skip over the prologue. So for the next Epicor installation guide that I write, if I need to tell you the answer to Life, the Universe and Everything, I’ll make sure to put it in a place where all customers – new, experienced, or any level in between – will find it. Also, don’t panic, I’ll make sure that the extraordinary consequences and how they are inextricably intertwined start on page 42.
Posted by Linda Robinson, Sr. Manager, Release Content, Epicor University