Technical writing audience

From Wikiversity
Jump to: navigation, search

back to Technical Writing Level 1

File:TechWriting2.jpg
Knowing your audience is key to effective technical writing.

Audience Analysis Lesson Plan[edit]

  1. Identify the audience
  2. List research items about the audience
  3. Write a simple instruction set for a persona
  4. Create a persona based on this research
  5. Write an introduction to a product for your persona


You'll need:

  • A photo
  • A product
  • A wiki page

Student Wiki Pages[edit]

If you want feedback on your course work, then put it online and add a link to the discussion page. Your fellow students and instructors will assist you.

Learn more about Fred and see some sample exercises.

  • Telecommunications Operator Persona: Michal


Audience Analysis[edit]

Writing for the audience

Documentation is a form of support and product marketing for the audience it targets.  

Good technical writers have the ability to transfer the knowledge of subject-matter experts to the end user through their documentation. It is important to research the product for which you are writing and communicate with the person for whom you are writing.

How can you research potential readers?[edit]

A good starting point in research is the observation of people. Observe your peers and determine common attributes. Writing for a skilled audience relies on technical accuracy; therefore, an understanding of the business environment, technology, and theory is essential.

Tools we can use to help us in our research include:

  • surveys and questionnaires
  • popular opinion and stereotypes
  • personal experience
  • brainstorming documentation efforts
  • audience feedback

Additional research tools are found in the business environment. For example, a marketing department usually has a clear idea of intended buyers of software. To best utilize their skill sets, determine if a designated resource is accessible and arrange a meeting with them. A good resource can provide marketing analysis, possible pitfalls of terminology usage, and demographics in detail. This information is a good first step in understanding audience analysis.

End user analysis:

  • Their level of experience with similar products
  • How they intend to use the software
  • The jargon they use in their work

Environment and Expectations[edit]

If your intended audience is completely new to the target technology, you may have to include quite elementary instructions in your materials; but most readers today have at least some familiarity with these topics, and there is no need to waste their time repeating it. By finding out how familiar the audience is with similar technology, you save your time and the reader's too.

Most people don't buy software because they are interested in the names of all the buttons. Instead, they buy the software so that they can achieve a goal through completing specific tasks. So your instructions must concentrate on the steps they need to reach their goal. I use a word processor so that I write and format text, not because I love hunting for menu items and building macros. Hence, I expect instructions to show me how to create, save, edit, and finally print a letter or some other document. Always focus on the task the user wants to complete, and describe it simply and directly.

So long as your software follows the conventions found in most similar products (i.e., a "file" isn't called a "rock") then you can use the same conventions. The Microsoft Manual of Styleis a good source for these software-naming conventions. Other terms that are specific to the software's intended purpose should come from the prospective users. If the end users of your software always refer to something as the "skryx", then so should you. A software manual is not the place to try to change their terminology, but a place to reflect it so that readers immediately feel comfortable and confident that you understand them and will help.

Your reader's environment affects what you write, and its format.

This leads to some basic questions:

  • What does your reader need to know?
  • Where does s/he need to know it?
  • When does s/he need to learn it?

Exercise 1[edit]

Use search engines and Wikipedia to research the background of wiki contributors. List what is known about these people. List what is unknown.

Personas[edit]

Even if you have a pretty good idea of the end users of the software, it's still not very effective to write for a generalized "they." You could solve the problem by always writing for your mom, but inevitably you'll find yourself writing for people so very unlike your mother that it simply won't work. Technical writers tend to document many different types of technology, and this means writing for very different audiences.

Alan Cooper has proposed a workable solution. He suggests creating fictional but complete personas for each project, and then writing for the personas.

While creating a fictional character may seem to be an odd start to the process of documenting technological products and processes, it usually works. Why? Because having a persona allows you to think deeply about your audience and cater the information to their needs. Then you can select the appropriate "natural" metaphors and data structures they will understand.

Personas are hypothetical archetypes, or "stand-ins" for actual users that drive the decision making for interface design projects.

  • Personas are not real people, but they represent real people throughout the design process
  • Personas are not "made up"; they are discovered as a by-product of the investigative process
  • Although personas are imaginary, they are defined with significant rigor and precision
  • Names and personal details for personas are made up to make them more realistic
  • Personas are defined by their goals
  • Interfaces that satisfy personas' needs and goals are built

Source: Alan Cooper, The Inmates Are Running the Asylum: Why High-Tech Products Drive Us Crazy and How to Restore the Sanity Indianapolis: Sams, 1999, pp. 123-24. (Wording condensed and modified.)

Exercise 2[edit]

Write "How to make instant coffee" steps for Wing Lee.

Exercise 3[edit]

Create a detailed persona of a "typical" Wiki user, including age, family background, education, and experience with computers.

  • Describe how they are using Wiki to achieve life goals.
  • Describe what tasks they will complete with Wiki.
  • What terms, specific to Wiki, are new to them.

Identity[edit]

Who are they? Where do they live? What language do they speak? How old are they? Do they have a family? How do they look for others? What is their need?

Needs[edit]

Why would they want to use your product? What do they wish to achieve? What are their goals?

Attitudes[edit]

Does your audience hate reading? Maybe you should draw a picture. Do they distrust technology? Consider using a very informal voice. Do they love details and examples? What is their previous experience with user documentation?

Expectations[edit]

Based on their previous experience, what do they expect out of what you're writing? Overviews? Details?

If they want to use the product without any details, write something very compact to satisfy them; but if they are expecting detailed technical specifications, a general introduction will not meet their goals. You must know their expectations in advance of planning your documents. Sometimes, product marketing can help you find out what they expect, or you may look at competing products.

Personas are simply hypothetical types of real users. Describe your persona’s goals, experience, environment, and expectations. Then write and structure your information in such a way that it serves those goals.

  1. Identify key users
  2. Create users’ persona
  3. Identify users’ goals
  4. Define tasks to accomplish these goals

Essential Persona Details[edit]

  • A name (a real name like Greg or Madeline, etc.)
  • Age
  • A photo
  • Personal information, including family and home life
  • Work environment (the tools used and the conditions worked under, rather than a job description)
  • Computer proficiency and comfort level with using the Web
  • Pet peeves and technical frustrations
  • Attitudes
  • Motivation or "trigger" for using a high-tech product (not just tasks, but end results)
  • Information-seeking habits and favorite resources
  • Personal and professional goals
  • Candid quotes

Source: Alan Cooper, The Inmates Are Running the Asylum: Why High-Tech Products Drive Us Crazy and How to Restore the Sanity, Indianapolis: Sams, 1999, Chapter Nine. (Wording condensed and modified.)

Creating a persona[edit]

After you have conducted as much audience analysis as is practical, you should have a good idea of the composite of people who will use the software. From this background data, you simply dream up a representative of those people. Give this person a name, say "John Smith", and appropriate details about their life. Where did they go to school? Do they have kids? What kind of car do they drive?

By formulating these details and writing them down, you begin to delve into the motivations and goals of this persona. The question, "what do they want from life?" gives you their goals. From these goals, you can fit in how the software helps them.

For example: John Smith, a thirty-four year old firefighter with a six year old daughter and a new pickup, wants to keep in contact with his family through a new voice over IP product. He's already familiar with telephones, and has used email and even IRC a few times. He has two years of college and sometimes reads Stephen King novels, but doesn't ever read "computer books".

From this, you would see that to help John make and receive telephone calls on his computer, you'd be wasting your time putting together a detailed technical description in printed form. Instead, you'd make the interface similar to email, and use the metaphor of standard telephones where practical. John wouldn't have to search for how to use something he's already familiar with, and could get right to the business of telling Grandma about his daughter's birthday party.

Exercise 4[edit]

Describe Wikipedia to your persona.

Essential Reading[edit]

Further Reading[edit]

back to Technical Writing Level 1

How to edit Wiki

Wikiversity Main Page