Technical writing/Audience

From Wikiversity
Jump to navigation Jump to search

back to Technical Writing Level 1

Audience Analysis Lesson Plan[edit | edit source]

  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 | edit source]

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 | edit source]

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 | edit source]

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 | edit source]

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 | edit source]

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

Wikipedia contributors, who are commonly called Wikipedians, are a group of diverse people all over the world who have made the conscious decision to come together and form a community that promotes knowledge acquisition. Wikipedians are bold internet extroverts who create and maintain the online encyclopedia Wikipedia with accessible and comprehensive knowledge about every field possible. They are time conscious and always reading to make sure articles are well edited.

It's fortunate that unregistered Wikipedians contribute massively to the site, because registered members often lack commitment. Only 1% of the registered editors are functional, with the likes of Steven Pruitt (American) topping the chart with highest number of edits made on English Wikipedia.

Wikipedians pose great skills in content generation, editing, and writing clear and concise articles for different audiences.

Personas[edit | edit source]

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 | edit source]

Create a detailed persona of a "typical" Wiki user, including

age = 23 years, family background : Average standard of livelihood, Catholics, education : University, study History experience with computers : No IT skills

  • Describe how they are using Wiki to achieve life goals; Research
  • Describe what tasks they will complete with Wiki; online courses daily
  • What terms, specific to Wiki, are new to them; RAM, HARD AND SOFTWARE, neologism

Identity[edit | edit source]

1) Who are they?


2) Where do they live?

Africa, Cameroon

3) What language do they speak?


4) How old are they?


5) Do they have a family?


6) How do they look for others?

Mobile communications and vacations

7) What is their need?

To learn IT

Needs[edit | edit source]

1) Why would they want to use your product?

Wikipedia provides easy to read information on IT for all academic levels OR IQ

2) What do they wish to achieve? To learn IT skills in shortest time possible 3):What are their goals?

Become IT expert

4) What do they want to read?

every information on IT

5) Why do they want to read you?

Wikipedia makes IT information available at little or not cost, all you need is dedication

Attitudes[edit | edit source]

Does your audience hate reading? NO Do they distrust technology? they are very innovative and technology friendly Do they love details and examples? Yes, its elaborate What is their previous experience with user documentation? No experience

Expectations[edit | edit source]

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: University history students
  2. Create users’ persona: they in their 20s, active mindsets, love reading and skill driven
  3. Identify users’ goals: Become IT experts
  4. Define tasks to accomplish these goals: 3 hours of online encyclopedia learning everyday

Essential Persona Details[edit | edit source]

  • A name: Dris
  • Age: 23 years
  • A photo
  • Personal information: Master student of University of Buea, department history, Volunteers in community building, plays football, comes from a family of 7 siblings, have strong will power
  • Work environment: can withstand adverse working conditions like angry boss, people person and team player
  • Computer proficiency and comfort level with using the Web: very low, intimidated with web languages
  • Pet peeves and technical frustrations:Can't use microsoft word to write final year project
  • Attitudes : eager to learn
  • Motivation or "trigger" for using a high-tech product : Have an IT understanding, help friends struggling with research writing and editing.
  • Information-seeking habits and favorite resources : Wikipedia,edu, org
  • Personal and professional goals : Become an IT expert and gain employment in a renowned company some day
  • Candid quotes: Consistency is key to success

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 | edit source]

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 3[edit | edit source]

Describe Wikipedia to your persona. Wikipedia is a community of people who go the extra miles to make sure information on every field is available online and made accessible and readable by any kind of audience (you).

Essential Reading[edit | edit source]

Further Reading[edit | edit source]

back to Technical Writing Level 1

How to edit Wiki

Wikiversity Main Page