Skip to main content

New Technical Writer: The Four Dimensions Of Your User/reader


To create an effective User Document, the writer must know who he/she is writing for. This article presents four dimensions (Skills, Attitude, Knowledge and Experience) for describing the User of your product (your Documentation Reader), and how to build a Persona that turns your generic User into an almost-real person. The article stresses the need to actually USE this information when structuring and writing your User Document.

GETTING INFORMATION ABOUT YOUR USER

The marketing department or product development team should be able to tell you who the intended User of the product is. (If they cannot, then the product is in big trouble.) Ask them to provide you with a complete description of the User. Ask them if their description can be make less strict (requiring fewer skills, ect.) and thus be applicable for a wider audience. Ask them how sure they are of their intended Users.

Ask them if they created a "Persona" (see below) to design the product. If so, ask them for the description of that Persona.

We will use this information to analyze your User in four dimensions. We will then re-build the ideal User into an almost-real person, who you can use to help design and write your User Document.

Timing: My estimate is that if the communication paths between you and the marketing and development teams are effective, then you should be able to complete this series of steps in a few hours spread over several days. This description of your User/Reader is an essential element in structuring and writing your User Document.

THE FOUR DIMENSIONS OF YOUR USER (Reader of your Document)

Four dimensions define your User/Reader. These dimensions are:

* Skills

What skills do you assume that your Reader must have in order to understand your User Document? (These are the skills that you assume that they have when they START to read your User Document... not the ones that you will teach them in the User Document.)

In a classic example of failure, a company that taught software programming did not specify that its students had to know how to use a particular computer word processor. As a result, students spent 80% of the class time learning how to use the word processor, rather than learning to write programs. The class was a failure.

List the skills that you expect your Reader to have.

* Attitude

Your Reader's attitude is almost always a combination of anger (impatience at having to read this stuff instead of using the product), and fear (something is not working the way your Reader expects it to). Write with compassion for your Reader. Are there other attitudes that may affect how your Reader uses the product and your documentation?

* Knowledge

What information do you expect the Reader to have when they read your User Document? Is there something that you expect your readers to understand or to have to figure out for themselves? If there are such items, then you should tell your Reader where to get the needed background information.

* Experience

Skills plus practice, yields experience. Are there any experiences that you expect your Readers to have, so that they can understand how to use the product or understand what you are writing? BEWARE of your Readers' experiences that may negatively affect how they use your product. One example is a product that radically changes the way that the User currently does things. Devote some space in your User Document to overcoming these problematic experiences.

WRITE FOR THE SAKE OF YOUR READER

These four dimensions spell out the word "SAKE." This reminds us to write for the SAKE of our Readers. You use these four dimensions when generating the topics for your User Document, as well as reviewing the material that you have written. These are topics for other articles in this "New Technical Writer" series.

Make sure that you tell your Reader about any SAKE assumptions that you make about them. Thus if you assume them to have a special skill, such as "welding steel" then tell them your assumption early in the User Document. If possible, tell them where they can get the background SAKE items that they might need. For example, if you assumed that your Reader has the skill to identify a certain bird, then tell them were to learn to identify that bird (perhaps with a link or reference to a birding authority).

You want to avoid situations like the one in the example above: the unstated requirement for knowing a specific word processor that ruined a programming class. Is the assumption that everybody knew how to use that esoteric word processor a reasonable one? The course developers should have checked with their sales department, since they sold the course to students who could not possibly have known about that esoteric word processor.

You really must clearly state (early in your User Document) any out of the ordinary assumptions that you make about your Reader.

YOUR READER AS A REAL PERSON

From the SAKE dimensions, and from the descriptions of the typical User of the product that you got from the marketing or development teams, you will create a real-as-possible person to represent your typical User. Such a representation is called a Persona in the product development industry. The Persona is also your User Document Reader.

If the marketing and development teams use a Persona, and they provided a description to you, then use their Persona. You may have to add some description to it.

If you have to create a Persona, follow these steps (overview):

1. Imagine the generic User of your product.

2. Focus on this User. Describe the User. Think about his/her background, education, family, hobbies, interests. The goal is to make your generic User as tangible as possible.

3. Perhaps give the User a name, and even spend a minute or two to find a photograph of this Persona.

4. Evaluate for yourself if this Persona is a good representation of the User. Make changes as necessary.

Think about how the Persona got your product (for example, did they purchase it, did it come bundled with some other product, was it a gift, etc.). Think about what they are most likely to want to do with your product.

Later we will use the Persona to help define the topics of the User Document, and to help you write the actual text.

CHECK

Once you have generated the SAKE items and the Persona, write them out, and let members of the product and marketing teams check them for accuracy. "Accuracy" means "how closely your Persona coincides with their (product and marketing teams) view of the product's User." Discuss these points and make modifications as needed.

USING YOUR READER

Unfortunately most courses and books about technical writing stop here in their instructions about "knowing your Reader." These courses and books expect you simply to keep your Reader in mind when you write.

But you can and should do much more with the description of your Reader. The Persona will help you structure the information in the overall User Document; it will also help you write each of the topics.

The SAKE dimensions will help you as you revise your writing. Here the SAKE dimensions will

* help you avoid using language your Reader might not understand, and

* help you avoid jumps in your writing that your Reader will not be able to make.

Other articles in the "New Technical Writer" series will describe how to use your Persona and SAKE dimensions to design and write your User Document. See the "Resources" or "Author Information" section of this article to find links to related articles.

Comments

Popular posts from this blog

Top 10 [FREE] Writing Courses on Youtube That Are Packed With Massive Value

This is a friendly reminder that the best things in life really are FREE, and that includes full spectrum writing courses on Youtube that teach you just about everything you will need to know about operating as a competent, reliable, and skilled copywriter. Sure, you could pay for courses and there's nothing wrong with that. But why not take advantage of a free opportunity? Here are  Top 20 [FREE] Writing Courses on Youtube That Are Packed With Massive Value. 1. Simple Learning's Copywriting Course In this course, writers will learn how to write write product descriptions, multiply sales, and how to influence your readers. Course contains very little fluff - only the most important principles are shared throughout the video.  2. Simplilearn's Full Course Content Marketing Tutorial For Beginners Every content writer and marketer wants that coveted #1 spot on Google. Heck, most want to get to the front page at the very least. This course is all about ranking high on Google an

[SPONSOR] Mine Crypto With Your Phone For Free Now

Download the app and start mining with Android today Use PROMO Code: BBC896 to earn a 1.00℅ bonus on everything you mine The Road To Mass Adoption It’s common for cryptocurrencies to talk about seeking mass adoption. It’s far less common for them to make tangible progress towards that goal. Instant Cryptocurrency Payments We have a global patent pending on a technology that allows instant cryptocurrency payments. Instant payments will initially be in ETN but our patent also covers Bitcoin and other cryptocurrencies. The ability to SPEND ETN instantly is only half the equation. We are developing an API that will allow easy integration to ACCEPT ETN instantly. This means it will be simple to allow an ecommerce system to give instant check out, and even allow easy integration into ePOS systems (electronic point of sales systems or tills). USD 3 trillion opportunity By giving access to the 'gig economy' for the first time to over 350 million unb

[VIDEO] Dan Peña - How To Create Deal-flow | QLA Audio Newsletter

Dan Peña - How To Create Deal-flow | QLA Audio Newsletter Dan explains how to get started in Merger & Acquisition transactions. Known as the $50 Billion man, Dan has been the Chairman of over 50 firms and regularly holds Quantum Leap Advantage seminars out of his 15th Century castle in Scotland. He has created billions in equity value on behalf of his colleagues. One of his most recent mentees completed a $500 billion deal to create NEOM, the city of the future. Recording circa the mid 90s. Dan's website: https://www.danpena.co.uk/qla-for-dummies/ Here's the secret to becoming a great copywriter: http://bit.ly/2Ko76yU You are about to get full-blown access to money-making software that's jammed thousands of dollars into my forex account in the last few months: http://bit.ly/2kopNGi Never Seen Before! This Smart And Easy To Use Software Is Helping Forex Traders To Increase Their Profitability With Any System: http://bit.ly/2kVCnx6 Bots Room Has Be