what can your technical writer do? an acs wa branch presentation july 2008 stephanie bateman-graham...

What can your technical writer do?

An ACS WA branch

presentation

July 2008

Stephanie Bateman-Graham MACS PCP

What Can Your Technical Writer Do?2

SBG

Stephanie Bateman-Graham

1993 BA (Hons) Psychology, UWA Thesis “System Response Time and User

Performance in Data Entry” Centre for Computer Managed Training and Decision

Support Systems (COMTADSS) 2001 ACS Associate Member 2003 ACS Certification Program (Project

Management), regraded to Member Currently contracting to XempleX Pty Ltd as a

writer/analyst.

What Can Your Technical Writer Do?3

SBG

Introduction

Why are we here? What is a technical writer? How do they add value? How do you find them? How do you look after them?

What Can Your Technical Writer Do?4

SBG

Disclaimer

Stereotypes are useful, but are not an indicator of individual behaviour.

A composite view. Judge individuals on their merits.

What Can Your Technical Writer Do?5

SBG

Overview

Part I: What is a technical writer? Part II: How do they do it? Part III: Selection, Care and Feeding

What Can Your Technical Writer Do?6

SBG

Scenario

It doesn’t do what we wantIt doesn’t do what we needIt doesn’t do anything at allHelp doesn’tI hate itI can’t do my jobIt smells funnyThe consultant smells funny

The new system is perfect…

but the users complain:

What Can Your Technical Writer Do?7

SBG

A user

What Can Your Technical Writer Do?8

SBG

You are all individuals

What Can Your Technical Writer Do?9

SBG

Part I: What is a technical writer?

Part I: What is a technical communicator?

Part I: What is a technical and business communicator?

Part I: What is a technical and business and community communicator?

What Can Your Technical Writer Do?10

SBG

Typical Career Path

What Can Your Technical Writer Do?11

SBG

Generalist or specialist?

Swiss army knife Software manual writer

What Can Your Technical Writer Do?12

SBG

BusySmallWidgetCo

CEO

Developer(s)/IT Support/

Product Support/Consulting

Tester?

CTO Marketing/

Finance

Admin

What Can Your Technical Writer Do?13

SBG

BusySmallWidgetCo

CEO

Developer(s)

Tester

Admin

CTO

Marketing/Finance

Value-Added Reseller

Trainer

Support

Business Analyst

Project Manager

GUI Designer

Technical Writer

What Can Your Technical Writer Do?14

SBG

Technical Writer, and silver bullet?

Business analyst Project manager GUI designer Company secretary Researcher Editor Web designer Tester Diplomat Requirements analyst Indexer Data modeller User advocate

Animator Team leader Localisation manager Usability expert Graphic designer Web developer Illustrator Knowledge manager Trainer Marketing expert Curriculum developer Database administrator Caped crusader

What Can Your Technical Writer Do?15

SBG

Specialist roles

Design and Development Sales and Marketing Deployment End-user

What Can Your Technical Writer Do?16

SBG

Specialist: Design and development

Use Cases Requirements Enhancement requests Design documents Program text (e.g. labels, menus, error messages)

Test specifications Bug reports

What Can Your Technical Writer Do?17

SBG

Specialist: Sales and Marketing

Brochures Fact Sheets E-mail contact templates Web content White papers Product presentations

– PowerPoint– Animations– Film voiceover scripts

Reseller’s guide

What Can Your Technical Writer Do?18

SBG

Reseller’s Guide

Style guide for marketing messages Product and industry background Product features Quotation process Pricing

What Can Your Technical Writer Do?19

SBG

Specialist: Deployment

Change plans User education program Installation and configuration instructions Trainer-led training materials Support desk guides

What Can Your Technical Writer Do?20

SBG

Configuration guidelines

Consultant’s guide Map client business policy to product

technical system settings.

What Can Your Technical Writer Do?21

SBG

Policy >> Configuration

ClientConsultant

System Administrator

User

Describes policy

Translates policy to

configuration

Does configuration

Uses system

Prompts for policy

Trainer

Delivers training

What Can Your Technical Writer Do?22

SBG

Training materials

Curriculum Presentations Exercises Data Handouts Tests Certificates Student Guide: What to learn Trainer’s Guide: How to teach it

What Can Your Technical Writer Do?23

SBG

“Tech writers write software manuals”

What Can Your Technical Writer Do?24

SBG

Specialist: End user documentation

Glossary Index Goal-oriented user

guides Function-oriented

reference material Problem-oriented

troubleshooting guides

User Guides:– Install/Upgrade– Quick Start – Job-defined

Administrator Data entry Supervisor Sales

Self-paced training– Simulation-based– e-Learning

What Can Your Technical Writer Do?25

SBG

Where is the value?

Concept Development Sales Deployment Support

What Can Your Technical Writer Do?26

SBG

Efficiency

Organise information for busy people Fast access Templates

What Can Your Technical Writer Do?27

SBG

Consistency

Glossary of terms Similar widgets/processes for similar tasks Naming controls, commands Editing for consistent voice Templates

What Can Your Technical Writer Do?28

SBG

Acceptance

Understand the customer’s perspective and business needs. Answer this question:

“How can this tool help me to achieve my business goals?”

This is mere curiosity:

“What does this bit do? What happens when I press this button?”

What Can Your Technical Writer Do?29

SBG

Part II: How do they do it?

Listen Learn Plan Ask Challenge Do Translate Write Draw Test Revise

What Can Your Technical Writer Do?30

SBG

Listen

What Can Your Technical Writer Do?31

SBG

Learn

What Can Your Technical Writer Do?32

SBG

Ask

Is it supposed to

do that?

What Can Your Technical Writer Do?33

SBG

Do

What Can Your Technical Writer Do?34

SBG

Translate

Foreign language <=> Local language

Local dialect <=> Audience language

Technical language <=> Common language

Business language <=> Technical language

Business goals <=> Technical goals

Use cases <=> Functions

Words <=> Images

What Can Your Technical Writer Do?35

SBG

Logic

Value Q is derived from values R and S These nouns go with these verbs A is a precursor to B Person X must complete Task Y with data Z

What Can Your Technical Writer Do?36

SBG

Brief words of wisdom

Complex language does not make you look clever

Plain English is not an insult to the reader Consistent grammar, usage Controlled vocabulary

What Can Your Technical Writer Do?37

SBG

KISS

Elaborate linguistic structures absorb the reader’s cognitive capacity at the expense of their understanding of the subject matter.

Complex writing is distracting.

What Can Your Technical Writer Do?38

SBG

KISS

“Genius is the ability to reduce the complicated to the simple” – C. W. Ceram

“Do not accustom yourself to use big words for little matters” – Samuel Johnson

“The most valuable of talents is that of never using two words when one will do”– Thomas Jefferson

“Easy reading is damn hard writing” – Nathaniel Hawthorne

What Can Your Technical Writer Do?39

SBG

Please don’t try this at home

“THE EXCLUSIVE FOCUS ON UNIVERSAL PRINCIPLES AND STRONG NEGATIVE OBLIGATIONS DREW THE SPATIO-TEMPORALLY EGALITARIAN INTERPRETATION OF THE KERNEL OF THE NOTION OF SUSTAINABLE DEVELOPMENT TO THE SAME PREOCCUPATION WITH THE SURVIVAL OF THE HUMAN SPECIES THAT CHARACTERISES THE APOCALYPTIC VIEWS OF RADICAL ENVIRONMENTALISTS.”

Beekman, Volkert (2004), 'Sustainable development and future generations', Journal of Agricultural and Environmental Ethics, 17 (1), 3-22. Page 12.

What Can Your Technical Writer Do?40

SBG

Humour

Must have a sense of humour Must be able to restrain sense of humour

What Can Your Technical Writer Do?41

SBG

Contact with colleagues

Tech writer lists Professional associations Conferences/seminars/workshops Local groups

What Can Your Technical Writer Do?42

SBG

Part III: Selection, Care and Feeding

What Can Your Technical Writer Do?43

SBG

An investment

What is the project scale and requirements? What resources does the project need? How much work can one person do?

Small organisations – generalist Large organisation/project – specialist

What Can Your Technical Writer Do?44

SBG

Qualifications

Be able to write. Have research skills Understand the writing process Have empathy, imagination, curiosity,

attention to detail, learning ability, intelligence, problem solving ability, common sense...

What Can Your Technical Writer Do?45

SBG

Don’t laugh, it happened to me

…and every single technical writer I’ve ever spoken to.

What Can Your Technical Writer Do?46

SBG

Team player, leader or hermit?

Naturally team players Often required to be independent Good organiser, good negotiator Good manager?

What Can Your Technical Writer Do?47

SBG

Experience

ESSENTIAL: Minimum 2 years experience with HelpGadget v4.0, Office 2007, SAP and Oracle

(Please) don’t select rigidly on the basis of experience with a particular tool, product or industry

Look at broader experience Assess the portfolio

What Can Your Technical Writer Do?48

SBG

No experience desired

Experts make the worst teachers Novices require explicit information first Intermediate students may have to break bad

habits

What Can Your Technical Writer Do?49

SBG

Novice to Expert

Novice Intermediate Expert

Training Experience

Transition errors

“Beginner’s luck”

“Intuition”

Implicit Knowledge (Ideas)

Explicit Knowledge (Rules)

What Can Your Technical Writer Do?50

SBG

Feedback

Editing Proofing

– Accuracy– Readability– Legal– Press

Acceptance testing

What Can Your Technical Writer Do?51

SBG

Cracking the whip

Technical Writers like to be productive. Let them. Balance organisational tasks with

creative/content production tasks.

What Can Your Technical Writer Do?52

SBG

The Next-Generation Product Documentation Report:

Getting Past the “Throw It over the Wall” Approach

[The technical communicator is] the hub for information about a manufacturer's product [and] should be leveraged throughout the entire organization. . . .

The end result will be a more consistent and positive product information experience for end users at every customer touch point.

Aberdeen Group, December 2006.

What Can Your Technical Writer Do?53

SBG

Conclusion

Technical Writing is a profession Consider investing a senior technical writer

as a generalist in a small organisation Give them information and feedback Don’t spread them too thin. Choose the right one Let them do their thing

What Can Your Technical Writer Do?54

SBG

Contact

Stephanie Bateman-Graham

stephbg@acslink.net.au

0402 712 344